view INSTALL @ 1110:2ba52dbf2312

Add release instructions for new sets
author Andy Buckley <andy@insectnation.org>
date Tue, 17 Oct 2017 17:12:04 +0100
parents 8c2adb305932
line source
1 /**
2 @page install Installation instructions
4 @tableofcontents
7 @section downloads Source file downloads
9 The source files can be downloaded from https://www.hepforge.org/downloads/lhapdf
12 @section quickstart Quick start instructions
14 If you have a C++11 compiler, building LHAPDF >= 6.2 should be straightforward:
16 wget http://www.hepforge.org/archive/lhapdf/LHAPDF-6.X.Y.tar.gz
17 tar xf LHAPDF-6.X.Y.tar.gz
18 cd LHAPDF-6.X.Y
19 ./configure --prefix=/path/for/installation
20 make
21 make install
23 You will then need to install PDF data files, most easily using the "lhapdf"
24 manager script but also possible by manual download. See the LHAPDF website for
25 details.
27 On systems where you want to use non-system compilers and libraries, the
28 configure command will need to be a bit more complicated: see the following for
29 more information.
31 Version 6.2.0 of LHAPDF, and later, have no external library
32 dependencies. Earlier versions rely on the Boost C++ header library. We
33 recommend upgrading to the current series to avoid that complication (and
34 benefit from other improvements, too).
37 @section compilers Build tools
39 LHAPDF6 just needs your system to have a copy of Make and a C++11 compiler:
40 there is no Fortran code and hence no need for gfortran. We have tested with
41 both the g++ and clang++ compilers.
43 Note that fairly recent compiler versions are needed, to get C++11 support: g++
44 >= 4.8.5 and clang++ >= 3.3. The `-std=c++11` flag, if needed, will be added
45 automatically by the LHAPDF configure script.
47 Building LHAPDF is typically straightforward on Linux systems, including CC7
48 and Ubuntu. Mac OS X, however, can cause problems due to inconsistent compiler
49 and Python versions, and other such fun. If you want to build LHAPDF on a Mac,
50 please see @ref osx.
53 @subsection pyext Python
55 If you want to build the Python interface to LHAPDF (which is very nice!), you
56 will need the Python development headers to be installed (e.g. via the
57 `python-dev` Ubuntu package). If the `Python.h` header is not found by
58 `configure`, no Python extension module will be built.
61 @section lhapdf Building LHAPDF
63 If you have downloaded a release tarball for LHAPDF 6.X.Y, unpack it with `tar
64 xf LHAPDF-6.X.Y.tar.gz`, then `cd` to the newly-created directory.
66 @note If checking out from version control rather than unpacking a tarball,
67 again `cd` to the new directory, but you must then also run `autoreconf -i`
68 before proceeding to the instructions below. There will also be more
69 requirements for external packages if you build this way, since this is the
70 "developer" route to building LHAPDF and requires a bit more expertise.
72 Now you should run the `configure` script to analyse your machine, compiler,
73 etc. and set up the Makefiles. You will probably need to provide the `--prefix`
74 argument to `configure` to tell it where you want to install LHAPDF (probably
75 you don't want to install to `/usr/local`, which is the default). For example,
77 ./configure --prefix=$HOME/local
79 An example build script for LHAPDF6 on the CERN lxplus6 system is shown at the
80 end of these instructions.
83 @subsection altcomp Alternative compilers
85 If you want to use an alternative C++ compiler, then you can specify the CXX
86 variable on the command line. This is essential on OS X Mavericks and later,
87 where the consistent compiler suite is clang rather than gcc -- in that
88 situation, use:
90 ./configure --prefix=... CXX=clang++
92 The configure script will run and produce quite a bit of output from its various
93 tests. Hopefully everything will be successful: if it gets to the end without
94 stopping due to an error then all is well.
96 Then just call `make` to build the library (or e.g. `make -j4` to compile 4
97 files in parallel -- if your machine has enough processor cores to do so, even
98 `-j2` will speed up the build quite a bit). To install LHAPDF to the `--prefix`
99 location that you specified, call `make install`. You will (or at least
100 *should(!) find installed files in `$prefix/lib`, `$prefix/include/LHAPDF`, and
101 `$prefix/share/LHAPDF`.
104 @section lxplus Building on lxplus / LCG
106 CERN's lxplus6 shared system is always an awkward environment to build packages,
107 since the system compiler etc. are not part of the LCG supported list of
108 architectures.
110 The SLC6 system compiler is too old to support C++11, and hence
111 setting up a non-system compiler (and consistent Python) is mandatory even if not
112 wishing to interact with LCG/experiment tools; on CC7 the system compiler is (just)
113 new enough for C++11, and so you can use the system environment and make a completely
114 standard build if you don't need to be LCG-compatible.
116 Here is an example of how to build LHAPDF using LCG tools on lxplus6 and lxplus7 --
117 although you can of course use other compilers, Python versions, build flags, etc. as you wish.
119 ## Set up LCG compiler & Python (required on SLC6/lxplus6, optional on CC7/lxplus7)
120 source /cvmfs/sft.cern.ch/lcg/releases/LCG_87/gcc/4.9.3/x86_64-slc6/setup.sh
121 source /cvmfs/sft.cern.ch/lcg/releases/LCG_87/Python/2.7.10/x86_64-slc6-gcc49-opt/Python-env.sh
123 ## Make an install directory
124 mkdir local
126 ## Build LHAPDF
127 wget http://www.hepforge.org/archive/lhapdf/LHAPDF-6.X.Y.tar.gz -O- | tar xz
128 cd LHAPDF-6.X.Y
129 ./configure --prefix=$PWD/../local
130 make -j2 && make install
131 cd ..
133 ## Set environment variables
134 export PATH=$PWD/local/bin:$PATH
135 export LD_LIBRARY_PATH=$PWD/local/lib:$LD_LIBRARY_PATH
136 export PYTHONPATH=$PWD/local/lib64/python2.6/site-packages:$PYTHONPATH
138 ## Test the scripts
139 lhapdf-config --help
140 lhapdf list
143 @section osx Building on Mac OS X
145 Builds are typically straightforward on Linux, but Mac OS X unfortunately has a
146 long history of incoherent system compiler setups, which have been worked around
147 manually by users' private installations of Fink, MacPorts, HomeBrew and manual
148 tarball installations of required tools. These work-arounds can themselves be
149 the source of problems when the native compilers or Python libraries get
150 updated, and due to the ad hoc nature of such installations we are restricted in
151 how much we can help to get LHAPDF to compile on a broken system: it is the
152 user's responsibility to make sure that their machine has a consistent set of
153 build tools!
155 From experience, the simplest reliable route seems to be to
156 run a fresh copy of OS X 10.9 Mavericks (or later) without any additional manual
157 compiler installations: if you use the clang++ compiler on such a system,
158 LHAPDF6 building should "just work".
160 @note At the time of writing there is a bug in the Mac Python version which
161 requires that you call `export CPPFLAGS=-Qunused-arguments` and `export
162 CFLAGS=-Qunused-arguments` before building. Alternatively you can run the
163 configure script with `--disable-python`, which avoids the bug at the cost of
164 not building the very useful Python interface to LHAPDF.
166 The Mac OS X "Homebrew" system (http://brew.sh/) comes recommended by several
167 LHAPDF developers. Many HEP packages are already available for Homebrew via the
168 homebrew-hep project: http://davidchall.github.io/homebrew-hep/ . Success has
169 also been reported with the MacPorts system (http://www.macports.org/): please
170 see HepForge's information about MacPorts at https://www.hepforge.org/docs/macosx .
171 With both these approaches, you should set your environment to *only* use
172 compilers and Python from the Brew/Ports area and to ignore the system packages:
173 a hybrid approach will only cause unnecessary pain.
176 @section boost Boost (for LHAPDF < 6.2)
178 Until LHAPDF 6.2.0, we made use of header files from the Boost C++ utility
179 library (http://www.boost.org). This made building LHAPDF a bit more complex,
180 and for reference we include some troubleshooting information here... for
181 now. The much better solution, however, is to use the current version which has
182 no such dependency.
184 If Boost is installed in the system `/usr` directory tree, via your machine's
185 packaging system, it should be discovered automatically. If not, you will need to use
186 something like
188 ./configure --prefix=$HOME/local --with-boost=$HOME/pkgs/boost-1_58
190 for your LHAPDF configuration step.
192 On Linux machines, Boost this should typically be available via
193 your system's packaging mechanism, e.g. the `libboost-all-dev` package on Ubuntu
194 and other Debian derivatives. On Scientific Linux 6 the system installation of
195 Boost is sufficient.
197 Building Boost by hand is not particularly simple and should not be needed in
198 most cases: we recommend avoiding this! If you have access to the CERN AFS
199 filesystem, you can find builds of Boost for various platforms in the
200 `/afs/cern.ch/sw/lcg/external/Boost/` directory. If you really want or need to
201 do it manually, version 6.0.5 and later of LHAPDF only use Boost headers
202 (previous ones used compiled libraries) and rather than fully building Boost,
203 you can just use the header files direct from its source tarball: this is not
204 wonderfully neat, but is a lot easier than doing a full manual build and
205 installation of the Boost libraries.
208 */