/[escript]/release/5.1/doc/install/source.tex
ViewVC logotype

Contents of /release/5.1/doc/install/source.tex

Parent Directory Parent Directory | Revision Log Revision Log


Revision 5407 - (show annotations)
Thu Dec 18 02:48:24 2014 UTC (4 years, 5 months ago) by jfenwick
Original Path: trunk/doc/install/source.tex
File MIME type: application/x-tex
File size: 18317 byte(s)
release changes
1 %!TEX root = install.tex
2 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3 % Copyright (c) 2012-2014 by University of Queensland
4 % http://www.uq.edu.au
5 %
6 % Primary Business: Queensland, Australia
7 % Licensed under the Open Software License version 3.0
8 % http://www.opensource.org/licenses/osl-3.0.php
9 %
10 % Development until 2012 by Earth Systems Science Computational Center (ESSCC)
11 % Development 2012-2013 by School of Earth Sciences
12 % Development from 2014 by Centre for Geoscience Computing (GeoComp)
13 %
14 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
15
16 % Notes about compilers
17
18 \chapter{Installing from Source}\label{chap:source}
19
20 This chapter assumes you are using a unix/posix like system (including MacOSX).
21
22 \section{Parallel Technologies}\label{sec:par}
23 It is likely that the computer you run \escript on, will have more than one processor core.
24 \escript can make use of multiple cores [in order to solve problems more quickly] if it is told to do so,
25 but this functionality must be enabled at compile time.
26 Section~\ref{sec:needpar} gives some rough guidelines to help you determine what you need.
27
28 There are two technologies which \escript can employ here.
29 \begin{itemize}
30 \item OpenMP -- the more efficient of the two [thread level parallelism].
31 \item MPI -- Uses multiple processes (less efficient), needs less help from the compiler.
32 \end{itemize}
33
34 Escript is primarily tested on recent versions of the GNU and Intel suites (``g++'' / ``icpc'').
35 However, it also passes our tests when compiled using ``clang++''.
36
37 Our current test compilers include:
38 \begin{itemize}
39 \item g++ 4.7.2, 4.9.1
40 \item clang++ (OSX 10.9 default, OSX 10.10 default)
41 \item intel icpc v14
42 \end{itemize}
43
44 Note that:
45 \begin{itemize}
46 \item OpenMP will not function correctly for g++ $\leq$ 4.2.1 (and is not currently supported by clang).
47 \item icpc v11 has a subtle bug involving OpenMP and c++ exception handling, so this combination should not be used.
48 \end{itemize}
49
50 \subsection{What parallel technology do I need?}\label{sec:needpar}
51 If you are using any version of Linux released in the past few years, then your system compiler will support
52 \openmp with no extra work (and give better performance); so you should use it.
53 You will not need MPI unless your computer is some form of cluster.
54
55 If you are using BSD or MacOSX and you are just experimenting with \escript, then performance is
56 probably not a major issue for you at the moment so you don't need to use either \openmp or MPI.
57 This also applies if you write and polish your scripts on your computer and then send them to a cluster to execute.
58 If in the future you find escript useful and your scripts take significant time to run, then you may want to recompile
59 \escript with more options.
60
61
62
63 Note that even if your version of \escript has support for \openmp or MPI, you will still need to tell the system to
64 use it when you run your scripts.
65 If you are using the \texttt{run-escript} launcher, then this is controlled by the \texttt{-t} and \texttt{-p} options.
66 If not, then consult the documentation for your MPI libraries (or the compiler documentation in the case of OpenMP
67 \footnote{It may be enough to set the \texttt{OMP\_NUM\_THREADS} environment variable.}).
68
69 If you are using MacOSX, then see the next section, if not, then skip to Section~\ref{sec:build}.
70
71 \section{MacOS}
72 This release of \escript has only been tested on OSX 10.9 and 10.10.
73 For this section we assume you are using either \texttt{homebrew} or \texttt{MacPorts} as a package
74 manager\footnote{Note that package managers will make changes to your computer based on programs configured by other people from
75 various places around the internet. It is important to satisfy yourself as to the security of those systems.}.
76 You can of course install prerequisite software in other other ways.
77 For example, we have had \emph{some} success changing the default
78 compilers used by those systems. However this is more complicated and we do not provide a guide here.
79 Successful combinations of OSX and package managers are given in the table below.
80
81 \begin{center}
82 \begin{tabular}{|c|c|c|}\hline
83 & \texttt{homebrew} & \texttt{MacPorts} \\\hline
84 OSX 10.9 & Yes & No\\\hline
85 OSX 10.10& Yes & Yes\\\hline
86 \end{tabular}
87 \end{center}
88
89 \noindent Both of those systems require the XCode command line tools to be installed\footnote{As of OSX10.9, the
90 command \texttt{xcode-select --install} will allow you to download and install the commandline tools.}.
91
92 \section{Building}\label{sec:build}
93
94 To simplify things for people, we have prepared \texttt{_options.py} files for a number of
95 systems\footnote{These are correct a time of writing but later versions of those systems may require tweaks.
96 Also, these systems represent a cross section of possible platforms rather than meaning those systems get particular support.}.
97 The \texttt{_options.py} files are located in the \texttt{scons/templates} directory. We suggest that the file most relevant to your os
98 be copied from the templates directory to the scons directory and renamed to the form XXXX_options.py where XXXX
99 should be replaced with your computer's name.
100 If your particular system is not in the list below, or if you want a more customised
101 build,
102 see Section~\ref{sec:othersrc} for instructions.
103 \begin{itemize}
104 \item Debian - \ref{sec:debsrc}
105 \item Ubuntu - \ref{sec:ubsrc}
106 \item OpenSuse - \ref{sec:susesrc}
107 \item Centos - \ref{sec:centossrc}
108 \item Fedora - \ref{sec:fedorasrc}
109 \item MacOS (macports) - \ref{sec:macportsrc}
110 \item MacOS (homebrew) - \ref{sec:homebrewsrc}
111 \item FreeBSD - \ref{sec:freebsdsrc}
112 \end{itemize}
113
114 Once these are done proceed to Section~\ref{sec:cleanup} for cleanup steps.
115
116 All of these instructions assume that you have obtained the \escript source (and uncompressed it if necessary).
117 \subsection{Debian}\label{sec:debsrc}
118
119 \begin{shellCode}
120 sudo aptitude install python-dev python-numpy libboost-python-dev libnetcdf-dev
121 sudo aptitude install scons lsb-release libboost-random-dev
122 sudo aptitude install python-sympy python-matplotlib python-scipy
123 sudo aptitude install python-pyproj python-gdal
124 \end{shellCode}
125
126 \noindent Once \textit{Jessie} is released (or if \textit{wheezy-backports} is in your \texttt{apt} sources) you can use:
127 \begin{shellCode}
128 sudo aptitude install gmsh
129 \end{shellCode}
130 to add extra meshing functionality.
131
132 \begin{optionalstep}
133 If for some reason, you wish to rebuild the documentation, you would also need the following:
134 \begin{shellCode}
135 sudo aptitude install python-sphinx doxygen python-docutils texlive
136 sudo aptitude install zip texlive-latex-extra latex-xcolor
137 \end{shellCode}
138 \end{optionalstep}
139
140 \noindent In the source directory execute the following (substitute wheezy for XXXX):
141 \begin{shellCode}
142 scons -j1 options_file=scons/templates/XXXX_options.py
143 \end{shellCode}
144
145 \noindent If you wish to test your build, you can use the following:
146 \begin{shellCode}
147 scons -j1 py_tests options_file=scons/templates/XXXX_options.py
148 \end{shellCode}
149
150 \subsection{Ubuntu}\label{sec:ubsrc}
151
152 If you have not installed \texttt{aptitude}, then substitute \texttt{apt-get} in the following.
153 \begin{shellCode}
154 sudo aptitude install python-dev python-numpy libboost-python-dev
155 sudo aptitude install libnetcdf-dev libboost-random-dev
156 sudo aptitude install scons lsb-release
157 sudo aptitude install python-sympy python-matplotlib python-scipy
158 sudo aptitude install python-pyproj python-gdal gmsh
159 \end{shellCode}
160
161
162 \begin{optionalstep}
163 If for some reason, you wish to rebuild the documentation, you would also need the following:
164 \begin{shellCode}
165 sudo aptitude install python-sphinx doxygen python-docutils texlive
166 sudo aptitude install zip texlive-latex-extra latex-xcolor
167 \end{shellCode}
168 \end{optionalstep}
169
170 \noindent In the source directory execute the following (substitute precise, quantal or raring as appropriate for XXXX):
171 \begin{shellCode}
172 scons -j1 options_file=scons/templates/XXXX_options.py
173 \end{shellCode}
174
175 \noindent If you wish to test your build, you can use the following:
176 \begin{shellCode}
177 scons -j1 py_tests options_file=scons/templates/XXXX_options.py
178 \end{shellCode}
179
180
181
182 \subsection{OpenSuse}\label{sec:susesrc}
183 These instructions were prepared using release $13.2$.
184
185 \noindent Install packages from the main distribution:
186 \begin{shellCode}
187 sudo zypper install libboost_python1_54_0 libboost_random1_54_0
188 sudo zypper python-devel python-numpy libnetcdf_c++-devel
189 sudo zypper install python-scipy python-sympy python-matplotlib
190 sudo zypper install gcc gcc-c++ scons boost-devel netcdf-devel
191 \end{shellCode}
192 These will allow you to use most features except some parts of the \downunder inversion library.
193 If you wish to use those, you will need some additional packages [python-pyproj, python-gdal].
194 This can be done now or after Escript installation.
195
196 \begin{shellCode}
197 sudo zypper addrepo \
198 http://ftp.suse.de/pub/opensuse/repositories/Application:/Geo/openSUSE_13.2/ osgf
199 sudo zypper install python-pyproj python-gdal
200 \end{shellCode}
201
202 Now to build escript itself.
203 In the escript source directory:
204 \begin{shellCode}
205 scons -j1 options_file=scons/templates/opensuse13.1_options.py
206 \end{shellCode}
207
208 \noindent If you wish to test your build, you can use the following:
209 \begin{shellCode}
210 scons -j1 py_tests options_file=scons/templates/opensuse13.1_options.py
211 \end{shellCode}
212
213 \noindent Now go to Section~\ref{sec:cleanup} for cleanup.
214
215 \subsection{Centos}\label{sec:centossrc}
216 These instructions were prepared using centos release $7.0$.
217 The core of escript works, however some functionality is not availible because the default packages for some dependencies in Centos are too old.
218
219 \noindent Install packages from the main distribution:
220 \begin{shellCode}
221 yum install python-devel numpy scipy scons boost-devel
222 yum install python-matplotlib gcc gcc-c++
223 yum install boost-python
224 \end{shellCode}
225
226 The above packages will allow you to use most features except saving and loading files in \texttt{netCDF}
227 format and the \downunder inversion library.
228 If you wish to use those features, you will need to install some additional packages.
229 NetCDF needs to be installed when you compile if you wish to use it.
230 \begin{optionalstep}
231 \noindent Add the \texttt{EPEL} repository.
232 \begin{shellCode}
233 yum install epel-release.noarch
234 \end{shellCode}
235
236 \begin{shellCode}
237 yum install netcdf-devel netcdf_cxx_devel gdal-python
238 \end{shellCode}
239 \end{optionalstep}
240
241 \noindent For some coordinate transformations, \downunder can also make use of the python interface to a tool called \texttt{proj}.
242 There does not seem to be an obvious centos repository for this though.
243 If it turns out to be necessary for your particular application, the source can be downloaded.
244
245 \noindent Now to build escript itself.
246 In the escript source directory:
247 \begin{shellCode}
248 scons -j1 options_file=scons/templates/centos7_0_options.py
249 \end{shellCode}
250
251 \noindent Now go to Section~\ref{sec:cleanup} for cleanup.
252
253 \subsection{Fedora}\label{sec:fedorasrc}
254 These instructions were prepared using release $21.5$.
255
256 \noindent Install packages
257 \begin{shellCode}
258 yum install netcdf-cxx-devel gcc-c++ scipy
259 yum install sympy scons pyproj gdal python-matplotlib
260 yum install boost-devel
261 \end{shellCode}
262
263 \noindent Now to build escript itself.
264 In the escript source directory:
265 \begin{shellCode}
266 scons -j1 options_file=scons/templates/fedora21_5_options.py
267 \end{shellCode}
268
269 \noindent If you wish to test your build, you can use the following:
270 \begin{shellCode}
271 scons -j1 py_tests options_file=scons/templates/fedora21_5_options.py
272 \end{shellCode}
273
274 \noindent Now go to Section~\ref{sec:cleanup} for cleanup.
275
276 \subsection{MacOS 10.10 (macports)}\label{sec:macportsrc}
277
278 The following will install the capabilities needed for the \texttt{macports_10.10_options.py} file.
279
280 \begin{shellCode}
281 sudo port install scons
282 sudo port select --set python python27
283 sudo port install boost
284 sudo port install py27-numpy
285 sudo port install py27-sympy
286 sudo port select --set py-sympy py27-sympy
287 sudo port install py27-scipy
288 sudo port install py27-pyproj
289 sudo port install py27-gdal
290 sudo port install netcdf-cxx
291 sudo port instal silo
292 \end{shellCode}
293
294 \begin{shellCode}
295 scons -j1 options_file=scons/templates/macports_10.10options.py
296 \end{shellCode}
297
298
299 \subsection{MacOS 10.9, 10.10 (homebrew)}\label{sec:homebrewsrc}
300
301 The following will install the capabilities needed for the \texttt{homebrew_10.10_options.py} file.
302 OSX 10.9 can use the same file.
303
304 \begin{shellCode}
305 brew install scons
306 brew install boost-python
307 brew install homebrew/science/netcdf --with-cxx-compat
308 \end{shellCode}
309
310 There do not appear to be formulae for \texttt{sympy} or \texttt{pyproj} so if you wish to use those features, then
311 you will need to install them separately.
312
313
314 \begin{shellCode}
315 scons -j1 options_file=scons/templates/homebrew_10.10_options.py
316 \end{shellCode}
317
318
319 \subsection{FreeBSD}\label{sec:freebsdsrc}
320
321 At time of writing, \texttt{numpy} does not install correctly on FreeBSD.
322 Since \texttt{numpy} is a critical dependency for \escript, we have been unable to test on FreeBSD.
323
324 \begin{comment}
325 \subsubsection{Release 10.0}
326
327 Install the following packages:
328 \begin{itemize}
329 \item python
330 \item scons
331 \item boost-python-libs
332 \item bash
333 \item netcdf
334 \item silo
335 \item py27-scipy
336 \item py27-gdal
337 \item py27-matplotlib
338 \item py27-pyproj
339 \item py27-sympy
340 \end{itemize}
341
342 \noindent Next choose (or create) your options file.
343 For the setup as above the escript source comes with a prepared file in
344 \texttt{scons/templates/freebsd10.0_options.py}.
345 Finally to build escript issue the following in the escript source directory
346 (replace the options file as required):
347 \begin{shellCode}
348 scons -j1 options_file=scons/templates/freebsd10.0_options.py
349 \end{shellCode}
350
351 \emph{Note:} Some packages installed above are built with gcc 4.7. Somewhere
352 in the toolchain a system-installed gcc library is pulled in which is
353 incompatible with the one from version 4.7 and would prevent escript from
354 executing successfully. As explained in the FreeBSD
355 documentation\footnote{see \url{http://www.freebsd.org/doc/en/articles/custom-gcc/article.html}}
356 this can be fixed by adding a line to \texttt{/etc/libmap.conf}:
357 \begin{shellCode}
358 libgcc_s.so.1 gcc47/libgcc_s.so.1
359 \end{shellCode}
360
361 \end{comment}
362 \subsection{Other Systems / Custom Builds}\label{sec:othersrc}
363
364 \escript has support for a number of optional packages.
365 Some, like \texttt{netcdf} need to be enabled at compile time, while others, such as \texttt{sympy} and the projection packages
366 used in \downunder are checked at run time.
367 For the second type, you can install them at any time (ensuring that python can find them) and they should work.
368 For the first type, you need to modify the options file and recompile with scons.
369 The rest of this section deals with this.
370
371 To avoid having to specify the options file each time you run scons, copy an existing \texttt{_options.py} file from the
372 \texttt{scons/} or \texttt{scons/templates/} directories. Put the file in the \texttt{scons} directory and name
373 it \textit{yourmachinename}\texttt{_options.py}.\footnote{If the name
374 has - or other non-alpha characters, they must be replaced with underscores in the filename}.
375 For example: on a machine named toybox, the file would be \texttt{scons/toybox_options.py}.
376
377 Individual lines can be enabled/disabled, by removing or adding \# (the python comment character) to the beginning of the line.
378 For example, to enable OpenMP, change the line
379 \begin{verbatim}
380 #openmp = True
381 \end{verbatim}
382 to
383 \begin{verbatim}
384 openmp = True
385 \end{verbatim}
386
387 If you are using libraries which are not installed in the standard places (or have different names) you will need to
388 change the relevant lines.
389 A common need for this would be using a more recent version of the boost::python library.
390 You can also change the compiler or the options passed to it by modifying the relevant lines.
391
392 \subsubsection*{MPI}
393 If you wish to enable or disable MPI, or if you wish to use a different implementation of MPI, you can use the \texttt{mpi}
394 configuration variable.
395 You will also need to ensure that the \texttt{mpi_prefix} and \texttt{mpi_libs} variables are uncommented and set correctly.
396 To disable MPI use, \verb|mpi = 'none'|.
397
398 \subsubsection{Python3}
399 \escript works with \texttt{python3} but until recently, many distributions have not distributed python3 versions of their packages.
400 You can try it out though by modifying or adding the following variables in your options file:
401
402 \begin{verbatim}
403 pythoncmd='python3'
404 \end{verbatim}
405
406 \begin{verbatim}
407 usepython3=True
408 \end{verbatim}
409
410 \begin{verbatim}
411 pythonlibname='whateveryourpython3libraryiscalled'
412 \end{verbatim}
413
414
415
416
417 \subsubsection{Testing}
418 As indicated earlier, you can test your build using \texttt{scons py_tests}.
419 Note however, that some features like \texttt{netCDF} are optional for using \escript, the tests will report a failure if
420 they are missing.
421
422 \section{Cleaning up}
423 \label{sec:cleanup}
424
425 Once the build (and optional testing) is complete, you can remove everything except:
426 \begin{itemize}
427 \item bin
428 \item esys
429 \item lib
430 \item doc
431 \item CREDITS.TXT
432 \item README_LICENSE
433 \end{itemize}
434 The last two aren't strictly required for operation.
435 The \texttt{doc} directory is not required either but does contain examples of escript scripts.
436
437 You can run escript using \texttt{\textit{path_to_escript_files}/bin/run-escript}.
438 Where \texttt{\textit{path_to_escript_files}} is replaced with the real path.
439
440 \begin{optionalstep}
441 You can add the escript \texttt{bin} directory to your \texttt{PATH} variable.
442 The launcher will then take care of the rest of the environment.
443 \end{optionalstep}
444
445 \section{Optional Extras}
446
447 Some other packages which might be useful include:
448 \begin{itemize}
449 \item support for silo format (install the relevant libraries and enable them in the options file).
450 \item Visit --- visualisation package. Can be used independently but our \texttt{weipa} library can make a Visit
451 plug-in to allow direct visualisation of escript files.
452 \item gmsh --- meshing software used by our \texttt{pycad} library.
453 \item mayavi --- another visualisation tool.
454 \end{itemize}
455
456
457 %Need a better title but this is stuff like visit and silo (for non-debian distros)
458 %Perhaps - optional extras
459
460
461
462
463

  ViewVC Help
Powered by ViewVC 1.1.26