/[escript]/release/3.2/doc/install/srcommon.tex
ViewVC logotype

Contents of /release/3.2/doc/install/srcommon.tex

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3413 - (show annotations)
Fri Dec 10 02:12:57 2010 UTC (6 years, 10 months ago) by jfenwick
File MIME type: application/x-tex
File size: 12916 byte(s)
Tweaking version strings

1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2 %
3 % Copyright (c) 2003-2010 by University of Queensland
4 % Earth Systems Science Computational Center (ESSCC)
5 % http://www.uq.edu.au/esscc
6 %
7 % Primary Business: Queensland, Australia
8 % Licensed under the Open Software License version 3.0
9 % http://www.opensource.org/licenses/osl-3.0.php
10 %
11 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
12
13 % This file contains material common to all src distributions.
14
15 % The original version of this content came from the esscc twiki page maintained by ksteube
16
17 This chapter describes how to build \esfinley from source assuming that the dependencies are already installed (for example using precompiled packages for your OS).
18 Section~\ref{sec:deps} describes the dependencies, while Section~\ref{sec:compilesrc} gives the compile instructions.
19
20 If you would prefer to build all the dependecies from source in the escript-support packages please see Chapter~\ref{chap:allsrc}.
21 \esfinley is known to compile and run on the following systems:
22 \begin{itemize}
23 \item \linux using gcc\footnote{There are some problems with \openmp under gcc prior to version 4.3.2. Also do not link the gomp library with gcc 4.3.3 - it causes problems.}
24 \item \linux using icc on SGI ICE 8200. (At this stage, we do not recommend building with intel-11)\footnote{There is a bug in icpc-11 related to exception handling and openmp. This results in binaries which crash.}
25 \item \macosx using gcc
26 \item \winxp using the Visual C compiler (we do not specifically discuss Windows builds in this guide).
27 \end{itemize}
28
29 If you have compiled a previous version of \esfinley please note that the format of the \file{..._options.py} file has changed so you will not be able to reuse old options file for this build.
30
31
32 \section{External dependencies}
33 \label{sec:deps}
34 The following external packages are required in order to compile and run \esfinley.
35 Where version numbers are specified, more recent versions can probably be subsituted.
36 You can either try the standard/precompiled packages available for your operating system or you can download and build them from source.
37 The advantage of using existing packages is that they are more likely to work together properly.
38 You must take greater care if downloading sources separately.
39
40 \begin{itemize}
41 \item python-2.5.1 (\url{http://python.org}) \\-
42 Python interpreter (you must compile with shared libraries.)
43 \item numpy 1.1.0 (\url{http://numpy.scipy.org}) \\-
44 Arrays for Python
45 \item boost-1.35 (\url{http://www.boost.org}) \\-
46 Interface between C++ and Python
47 \item scons-0.989.5 (\url{http://www.scons.org/}) \\-
48 Python-based alternative to \texttt{make}.
49 \end{itemize}
50
51 The version numbers given here are not strict requirements, more recent (and in some cases older) versions are very likely to work.
52 The following packages should be sufficient (but not necessarily minimal) for Debian 5.0 (``Lenny''):
53 python-dev, libboost-python1.35-dev, scons, python-numpy, g++.
54
55 These packages may be required for some of the optional capabilities of the system:
56
57 \begin{itemize}
58 \item netcdf-3.6.2 (\url{http://www.unidata.ucar.edu/software/netcdf}) \\-
59 Used to save data sets in binary form for checkpoint/restart (must be compiled with -fPIC)
60 % \item vtk-5.0.4 (\url{http://www.vtk.org}) \\-
61 % Used to save VTK files for visualization
62 % \begin{itemize}
63 % \item cmake-2.4.6 (\url{http://www.cmake.org}) \\-
64 % Required to build VTK
65 % \item mesa-7.0.3 (\url{http://www.mesa3d.org})\\-
66 % Free OpenGL replacement used by VTK
67 % \end{itemize}
68 \item netpbm (\url{http://netpbm.sourceforge.com}) \\-
69 Tools for producing movies from images
70 \item parmetis-3.1 (\url{http://glaros.dtc.umn.edu/gkhome/metis/parmetis/overview}) \\-
71 Optimization of the stiffness matrix
72 \item MKL \\(\url{http://www.intel.com/cd/software/products/asmo-na/eng/307757.htm}) \\-
73 Intel's Math Kernel Library for use with their C compiler.
74 \item Lapack - Available in various versions from various places. \\
75 Currently only used to invert dense square matrices larger than 3x3.
76 \end{itemize}
77
78 The following packages might be useful for mesh generation:
79 \begin{itemize}
80 \item gmsh-2.2.0 (\url{http://www.geuz.org/gmsh}) \\-
81 Mesh generation and viewing
82 \begin{itemize}
83 \item fltk-1.1.9 (\url{http://www.fltk.org}) \\-
84 Required to build gmsh
85 \item gsl-1.10 (\url{http://www.gnu.org/software/gsl}) \\-
86 Required to build gmsh
87 \end{itemize}
88 \item triangle-1.6 (\url{http://www.cs.cmu.edu/~quake/triangle.html}) \\-
89 Two-dimensional mesh generator and Delaunay triangulator.
90 \end{itemize}
91
92 Packages for visualization:
93 \begin{itemize}
94 \item mayavi-1.5 (\url{http://mayavi.sourceforge.net}) \\-
95 MayaVi is referenced in our User's Guide for viewing VTK files
96 \item visit-1.11.2 (\url{https://wci.llnl.gov/codes/visit/}) \\-
97 A featureful visualization system with movie-making capabilities.
98 \end{itemize}
99
100 \section{Compilation}\label{sec:compilesrc}
101 Throughout this section we will assume that the source code is uncompressed in a directory called \file{escript.d}.
102 You can call the directory anything you like, provided that you make the change before you compile.
103
104 You need to indicate where to find the external dependencies.
105 To do this, create a file in the \file{escript.d/scons} directory called \file{x_options.py} where ``x'' is the name of your computer (output of the \texttt{hostname} command).
106 Please note that if your hostname has non-alphanumeric characters in it (eg - ) you need to replace them with underscores.
107 For example the options file for \texttt{bob-desktop} would be named \file{bob_desktop_options.py}.
108
109 From now on all paths will be relative to the top level of the source.
110 As a starting point copy the contents one of the following files into your options file:
111 \begin{itemize}
112 \item \file{scons/TEMPLATE_linux.py} (\linux and \macosx desktop)
113 \item \file{scons/TEMPLATE_windows.py} (\winxp)
114 \end{itemize}
115
116 This options file controls which features and libraries your build of escript will attempt to use.
117 For example to use OpenMP or MPI you will need to enable it here.
118
119 If you want to try escript out without customising your build, then change directories to \file{escript.d} and
120 \begin{shellCode}
121 scons
122 \end{shellCode}
123
124 \begin{verse}
125 If you are using a relatively recent version of Ubuntu this may produce errors.
126 The problem is the name of a library in Ubuntu packages.
127 Find the line in the options file you just created which reads
128 \begin{shellCode}
129 #boost_libs = ['boost_python-mt']
130 \end{shellCode}
131
132 You will need to change the name so it has a python version after it.
133 For example:
134 \begin{shellCode}
135 boost_libs = ['boost_python-mt-py26']
136 \end{shellCode}
137
138 Then run scons.
139 \end{verse}
140
141 If this works, then you can skip to Section~\ref{sec:diff}.
142 If not, then you will need to make some more modications to the the file.
143 Read on.
144
145 The template files contain all available options with a comment explaining the
146 purpose of each.
147 Check through the file and ensure that the relevant paths and names are correct
148 for your system and that you enable optional components that you wish to use.
149 For example, to use netCDF, find the netcdf-related lines, uncomment them
150 (i.e. remove the \# at the beginning of the lines) and change them according
151 to your installation:
152 \begin{shellCode}
153 netcdf = True
154 netcdf_prefix = '/opt/netcdf4'
155 netcdf_libs = ['netcdf_c++', 'netcdf']
156 \end{shellCode}
157
158 In this example, netCDF \emph{header} files must be located in
159 \file{/opt/netcdf4/include}\footnote{or \ldots/include32 or \ldots/include64 or \ldots/inc}
160 and the \emph{libraries} in \file{/opt/netcdf4/lib}\footnote{or \ldots/lib32 or \ldots/lib64}.
161 If this scheme does not apply to your installation then you may also specify
162 the include-path and library-path directly like so:
163 \begin{shellCode}
164 netcdf_prefix = ['/usr/local/include/netcdf', '/usr/local/lib']
165 \end{shellCode}
166 The order is important: the first element in the list is the
167 \emph{include}-path, the second element is the \emph{library}-path and both
168 must be specified.
169
170 If a line in the options file is commented out and you do not require the
171 feature, then it can be ignored.
172
173 To actually compile (if you have $n$ processors, then you can use \texttt{scons -j$n$} instead):
174
175 \begin{shellCode}
176 cd escript.d
177 scons
178 \end{shellCode}
179
180 As part of its output, scons will tell you the name of the options file it used
181 as well as a list of features and whether they are enabled for your build.
182 If you enabled an optional dependency and the library or include files could
183 not be found you will be notified and the build will stop.
184
185 Note, that you can override all settings from the options-file on the scons
186 command line. For example, if you usually build an optimized version but would
187 like to build a debug version into a separate directory without changing your
188 default settings, you can use:
189 \begin{shellCode}
190 scons debug=1 prefix=debugbuild
191 \end{shellCode}
192 This will install the binaries and libraries built in debug mode into
193 directories underneath \file{./debugbuild}.
194
195 To run the unit test suite that comes with the source code issue
196 \begin{shellCode}
197 scons all_tests
198 \end{shellCode}
199 Grab a coffee or two while the tests compile and run.
200 An alternative method is available for running tests on \openmp and \mpi builds.
201
202 \subsection{Compilation with \openmp}
203 \openmp is generally enabled by setting compiler and linker switches. For the
204 most common compilers these are automatically set by build system and all you
205 have to do is set the \texttt{openmp} option to True in your options file. If
206 this does not work or your compiler is different, then consult your compiler
207 documentation for the precise switches to use and modify the \texttt{omp_flags}
208 and \texttt{omp_ldflags} variables in your options file.
209 For example, for gcc compilers which support \openmp use:
210 \begin{shellCode}
211 openmp = True
212 omp_flags = '-fopenmp'
213 omp_ldflags = '-fopenmp'
214 \end{shellCode}
215 (The two latter settings can also be left out as this is the default OpenMP on gcc.)
216
217 You can test your \openmp-enabled build, e.g. using 4 threads by issuing
218 \begin{shellCode}
219 export ESCRIPT_NUM_THREADS=4
220 scons all_tests
221 \end{shellCode}
222
223 \subsection{Compilation with \mpi}
224 You need to have \mpi preinstalled on your system.
225 There are a number of implementations so we do not provide any specific advice
226 here.
227 Set the following variables in your options file to according to your
228 installation:
229 \begin{itemize}
230 \item \texttt{mpi} \\
231 which \mpi implementation (flavour) is used. Valid values are
232 \begin{itemize}
233 \item[\texttt{none}] \mpi is disabled
234 \item[\texttt{MPT}] SGI MPI implementation \\
235 \url{http://techpubs.sgi.com/library/manuals/3000/007-3687-010/pdf/007-3687-010.pdf}
236 \item[\texttt{MPICH}] Argonne's MPICH implementation \\
237 \url{http://www.mcs.anl.gov/research/projects/mpi/mpich1/}
238 \item[\texttt{MPICH2}] Argonne's MPICH version 2 implementation \\
239 \url{http://www.mcs.anl.gov/research/projects/mpi/mpich2/}
240 \item[\texttt{OPENMPI}] Open MPI \\
241 \url{http://www.open-mpi.org/}
242 \item[\texttt{INTELMPI}] Intel MPI \\
243 \url{http://software.intel.com/en-us/intel-mpi-library/}
244 \end{itemize}
245 \item \texttt{mpi_prefix} \\
246 where to find \mpi headers and libraries (see netCDF example above)
247 \item \texttt{mpi_libs} \\
248 which libraries to link to.
249 \end{itemize}
250
251 To test your build using 6 processes enter:
252 \begin{shellCode}
253 export ESCRIPT_NUM_PROCS=6
254 scons all_tests
255 \end{shellCode}
256 and on $2$ processes with $4$ threads each (provided \openmp is enabled)\footnote{Unless your system has $8$ cores expect this to be slow}:
257 \begin{shellCode}
258 export ESCRIPT_NUM_THREADS=4
259 export ESCRIPT_NUM_PROCS=2
260 scons all_tests
261 \end{shellCode}
262 Alternatively, you can give a hostfile
263 \begin{shellCode}
264 export ESCRIPT_NUM_THREADS=4
265 export ESCRIPT_HOSTFILE=myhostfile
266 scons all_tests
267 \end{shellCode}
268 Note that depending on your \mpi flavour it may be required to start a daemon
269 before running the tests under \mpi.
270
271 \subsection{Difficulties}\label{sec:diff}
272
273 \subsubsection{Mismatch of runtime and build libraries}
274 Most external libraries used by \esfinley are linked dynamically.
275 This can lead to problems if after compiling \esfinley these libraries are
276 updated.
277 The same applies to the installed Python executable and libraries.
278 Whenever these dependencies change on your system you should recompile
279 \esfinley to avoid problems at runtime such as load errors or segmentation
280 faults.
281
282 \subsubsection{\openmp builds segfault running examples}
283 One known cause for this is linking the \file{gomp} library with escript built using gcc 4.3.3.
284 While you need the \texttt{-fopenmp} switch you should not need to link \file{gomp}.
285
286

  ViewVC Help
Powered by ViewVC 1.1.26