ViewVC logotype

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

Parent Directory Parent Directory | Revision Log Revision Log

Revision 4673 - (hide annotations)
Thu Feb 13 08:14:11 2014 UTC (5 years, 3 months ago) by jfenwick
Original Path: trunk/doc/install/source.tex
File MIME type: application/x-tex
File size: 24302 byte(s)
Ammended install doco for OSX
1 jfenwick 4383 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2 jfenwick 4657 % Copyright (c) 2012-2014 by University of Queensland
3 jfenwick 4383 % http://www.uq.edu.au
4     %
5     % Primary Business: Queensland, Australia
6     % Licensed under the Open Software License version 3.0
7     % http://www.opensource.org/licenses/osl-3.0.php
8     %
9     % Development until 2012 by Earth Systems Science Computational Center (ESSCC)
10 jfenwick 4657 % Development 2012-2013 by School of Earth Sciences
11     % Development from 2014 by Centre for Geoscience Computing (GeoComp)
12 jfenwick 4383 %
13     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
15     % Notes about compilers
17     \chapter{Installing from Source}\label{chap:source}
19 jfenwick 4673 This chapter assumes you are using a unix/posix like system (including MacOSX).
20 jfenwick 4440
21 jfenwick 4673 \section{Parallel Technologies}\label{sec:par}
22     It is likely that the computer you run \escript on, will have more than one processor core.
23 jfenwick 4383 \escript can make use of multiple cores [in order to solve problems more quickly] if it is told to do so,
24     but this functionality must be enabled at compile time.
25 jfenwick 4673 Section~\ref{sec:needpar} gives some rough guidelines to help you determine what you need.
26 jfenwick 4383
27     There are two technologies which \escript can employ here.
28     \begin{itemize}
29     \item OpenMP -- more efficient of the two [thread level parallelism].
30     \item MPI -- Uses multiple processes (less efficient), needs less help from the compiler.
31     \end{itemize}
33 jfenwick 4673 Escript is primarily tested on recent versions of the GNU and Intel suites (``g++'' / ``icpc'').
34     However, it also passes our tests when compiled using ``clang++''.
35 jfenwick 4383 The table below shows what methods are available with which compilers.
37     \begin{center}
38     \begin{tabular}{|l|c|c|c|}\hline
39     & Serial & OpenMP & MPI \\\hline
40 jfenwick 4673 $\leq$ g++-4.2.1 & \checkmark & \raisebox{-0.1cm}{\footnotemark}& \checkmark \\\hline
41     g++ (recent $\geq 4.3.2$) & \checkmark& \checkmark& \checkmark \\\hline
42     icpc(10) & \checkmark& \checkmark& \checkmark \\\hline
43     icpc(11) & \checkmark& \raisebox{-0.1cm}{\footnotemark} &\checkmark \\\hline
44     icpc(12) & \checkmark& \checkmark&\checkmark \\\hline
45     clang++ & \checkmark& & \checkmark\\\hline
46 jfenwick 4383 \end{tabular}
47     \end{center}
48     \addtocounter{footnote}{-1}
49 jfenwick 4673 \footnotetext{The \openmp support in g++-4.2.1 is buggy/non-functional.}
50 jfenwick 4383 \addtocounter{footnote}{1}
51 jfenwick 4673 \footnotetext{There is a subtle bug in icpc-11 when \openmp and c++ exception handling
52 jfenwick 4383 are combined.}
54     \noindent Where both \openmp and \mpi are marked, \escript can be compiled with either or both.
55     A \checkmark mark means that combination passes our tests.
57 jfenwick 4673 \subsection{What parallel technology do I need?}\label{sec:needpar}
58     If you are using any version of Linux released in the past few years, then your system compiler will support
59     \openmp with no extra work; so you should use it.
60     You will not need MPI unless your computer is some form of cluster.
61 jfenwick 4383
62 jfenwick 4673 If you are using BSD or MacOSX and you are just experimenting with \escript, then performance is
63     probably not a major issue for you at the moment so you don't need to use either \openmp or MPI.
64     This also applies if you write and polish your scripts on your computer and then send them to a cluster to execute.
65     If in the future you find escript useful and your scripts take significant time to run, then you may want to reinstall
66     \escript with more options.
67 jfenwick 4383
68 jfenwick 4673 In general, for a single computer, \openmp will give better performance (both time and memory) so use it if possible.
69     If \openmp is not an option, then use MPI.
70 jfenwick 4383
71 jfenwick 4673 Note that even if your version of \escript has support for \openmp or MPI, you will still need to tell the system to
72     use it when you run your scripts.
73     If you are using the \texttt{run-escript} launcher, then this is controlled by the \texttt{-t} and \texttt{-p} options.
74     If not, then consult the documentation for your MPI libraries (or the compiler documentation in the case of OpenMP
75     \footnote{It may be enough to set the \texttt{OMP\_NUM\_THREADS} environment variable.}).
76 jfenwick 4383
77 jfenwick 4673 If you are using MacOSX, then see the next section, if not, then skip to Section~\ref{sec:build}.
78 jfenwick 4383
79 jfenwick 4673 \section{MacOS}
80 jfenwick 4383
81 jfenwick 4673 To build \escript from source you need to choose and install the following (if you already have some parts installed, skip
82     that section).
83     \begin{itemize}
84     \item \texttt{XCode} and the associated command line tools. [Section~\ref{sec:initcompiler}]
85     \item A package manager. [Section~\ref{sec:osxpackagemanager}]
86     \item A compiler. [Section~\ref{sec:osxcompiler}]
87     \end{itemize}
88 jfenwick 4383
89 jfenwick 4673 As noted above, different compilers have varying support for parallel processing technologies so your choice of
90     compiler may limit your options of parallel technologies.
91     Once you have the pieces in this section, go to Section~\ref{sec:build} for build instructions.
92 jfenwick 4383
93 jfenwick 4673 \subsection{Initial compiler}\label{sec:initcompiler}
94     \emph{This information is as accurate as far as we can tell at time of writing but things may change.}
95 caltinay 4491
96 jfenwick 4673 Even if you wish to install and use a different compiler later, the first step is generally
97     to get some compiler onto your system.
98     This is a bit harder on MacOS than on other systems which either provide a compiler as part of the base install (BSD) or allow
99     people to download one as part of the install process (Linux).
100     In earlier releases of its operating system (``Snow Leopard'' and earlier), Apple included an optional ``developer tools'' package (\texttt{XCode}) on the install media.
101     For more recent releases, \texttt{XCode} is available for ``free'' from Apple's application store.
102     Why the quotes around ``free''?
103     The only way to access the application store is with an AppleID which requires either:
104 jfenwick 4383 \begin{itemize}
105 jfenwick 4673 \item purchasing an iTunes gift card.
106     \item giving Apple access to your credit card.
107     \item signing up as an Apple developer\footnote{If you do this you can download a ``command line tools'' package
108     which installs the relevant compilers without needing to install all of \texttt{XCode}.} and giving up personal information.
109 jfenwick 4383 \end{itemize}
111 jfenwick 4673 If you install \texttt{XCode}, you will need to download the ``command line tools'' optional package [see \texttt{XCode} documentation for details].
112 jfenwick 4383
113 jfenwick 4673 There are also a number of projects on the net which aim to deliver compilers for MacOS.
114     Use at your own risk.
115     For example:
116 jfenwick 4383 \begin{itemize}
117 jfenwick 4673 \item \url{http://hpc.sourceforge.net}
118     \item \url{http://kennethreitz.org/experiments/xcode-gcc-and-homebrew}
119 jfenwick 4383 \end{itemize}
121 jfenwick 4673 \subsection{OSX Package Managers}\label{sec:osxpackagemanager}
122     Once you have a working compiler, you will need to consider how you will install the components \escript needs.
123     While it is certainly possible to compile and install these pieces manually, it can be easier to use a tool
124     which handles some of the details for you.
125     This is especially true if you will need to uninstall or upgrade them later.
126 jfenwick 4383
127 jfenwick 4673 On OSX, there are a number of options.
128     The popular ones at time of writing seem to be \texttt{macports} and \texttt{homebrew}.
129     (We have not experimented with \texttt{fink}).
130     \escript does not assume that you are using a particular package manager\footnote{or even if you are using one at all.}.
131     The configuration instructions/files in this guide are just examples that we have found to work.
132 jfenwick 4383
133 jfenwick 4673 Note that package managers will make changes to your computer based on programs configured by other people from
134     various places around the internet.
135     It is important to satisfy yourself as to the security of those systems.
136 jfenwick 4383
137 jfenwick 4673 Please consult the documentation for your chosen package manager to determine how to set it up.
138 jfenwick 4383
139 jfenwick 4673 \subsection{A compiler}\label{sec:osxcompiler}
140     While the command line tools described in \ref{sec:initcompiler}, do contain a c++ compiler, in recent versions of OSX,
141     it is likely to be some version of \texttt{clang++}\footnote{even if it is
142     labelled as g++ it is likely clang++ under the hood.}.
143     If you don't need \openmp or genuine \texttt{g++} or you have installed an \openmp supporting compiler
144     using some other method, then you can skip to Section~\ref{sec:build}.
145 jfenwick 4383
146 jfenwick 4673 If you are still reading this part, we assume that you wish to use \texttt{g++} to build escript on your system and that you are
147     using a package manager.
148     The challenge here isn't installing the compiler itself.
149     The issue is that the other dependencies that \escript needs have
150     probably\footnote{or ``will probably be compiled'' in the case of \texttt{homebrew}.} been compiled by \texttt{clang} rather than the compiler
151     you want to use.
152     A lot of the time this is fine, but in the case of \texttt{c++} libraries such as \texttt{boost}, the result can be two different
153     standard c++ libraries\footnote{\texttt{libstdc++} and \texttt{libc++} on OSX 10.9.} being used in the same program and confusing matters.
154     Apart from giving up, there are two ways to try to solve this problem.
155     \begin{enumerate}
156     \item Changing the compiler that your package manager uses to compile its packages.
157     \emph{This is not for the faint hearted!} But we do provide some instructions in Appendix~\ref{chap:chcomp}.
158     \item Install most of the libraries using your package manager to install most things and then compile the c++ parts yourself.
159     (The most important one is texttt{boost}).
160     We have tested this on Macports and it works well. The only trick is to make sure that your ``replacement'' components are in a separate
161     directory which is ahead of you Macports directory in the various paths (\texttt{PATH, LD\_LIBRARY\_PATH, DYLD\_LIBRARY\_PATH}).
162     \end{enumerate}
167     % \subsection{Packaging System}
168     % The packaging system (also known as the package manager) is the tool you use to search for and install new open source software.
169     % For Linux, there will be one set up by default: the apt tools on Debian and Ubuntu, yast on Suse, yum on the RedHat family.
170     % On BSD systems this will be a combination of \texttt{pkg_add} and the \texttt{ports} tree.
171     %
172     % For MacOS, this is a bit more tricky.
173     % There are a number of possible systems including \texttt{macports} and \texttt{homebrew}\footnote{There is also \texttt{fink},
174     % but we have not experimented with that.}, but they do not come pre-installed so if you want to make use of one you will need
175     % you will need to install it.
176     %
177     % Packaging systems will make changes to your computer based on programs configured by other people from
178     % various places around the internet.
179     % It is important to satisfy yourself as to the security of those systems.
180     %
181     % If you are using Linux or have decided that you don't want to use OpenMP skip to Section~\ref{sec:build}.
182     %
183     %
184     % \textsl{This whole section could be moved to an appendix.
185     % Need to make it clear somewhere near that it is not intended to be complicated but to give options.
186     % }
189 jfenwick 4384 % make it clear that escript can be customised to use whatever you have
190 jfenwick 4383
191 jfenwick 4384 %Should include optional customisation
192 jfenwick 4383
193 jfenwick 4384 %Talk about options_files and the ability to specify them
194 jfenwick 4383
195 jfenwick 4384 %talk about -j1 and replacing it with more ops
196     %Talk about installation prefix
197 jfenwick 4383
198 jfenwick 4384 %also note that this doesn't build the doco but we do have downloads for that or you can install extra packages
199 jfenwick 4383
200 jfenwick 4440 \section{Building}\label{sec:build}
201 jfenwick 4383
202 jfenwick 4439 To simplify things for people, we have prepared \texttt{_options.py} files for a number of
203     systems\footnote{These are correct a time of writing but later versions of those systems may require tweaks.
204     Also, these systems represent a cross section of possible platforms rather than meaning those systems get particular support.}.
205 jfenwick 4440 If your particular system is not in the above list, or if you want a more customised
206     build\footnote{for example, you want MPI functionality or you wish to use a different compiler},
207 jfenwick 4439 see Section~\ref{sec:othersrc} for instructions.
208     \begin{itemize}
209     \item Debian - \ref{sec:debsrc}
210     \item Ubuntu - \ref{sec:ubsrc}
211     \item OpenSuse - \ref{sec:susesrc}
212     \item Centos - \ref{sec:centossrc}
213     \item Fedora - \ref{sec:fedorasrc}
214     \item MacOS (macports) - \ref{sec:macportsrc}
215     \item MacOS (homebrew) - \ref{sec:homebrewsrc}
216     \item FreeBSD - \ref{sec:freebsdsrc}
217     \end{itemize}
218 jfenwick 4383
219 jfenwick 4439 Once these are done proceed to Section~\ref{sec:cleanup} for cleanup steps.
220 jfenwick 4384
221 jfenwick 4439 All of these instructions assume that you have obtained the source (uncompressed it if necessary).
222     \subsection{Debian}\label{sec:debsrc}
223 jfenwick 4384
224 jfenwick 4439 \begin{shellCode}
225     sudo aptitude install python-dev python-numpy libboost-python-dev libnetcdf-dev
226 sshaw 4551 sudo aptitude install scons lsb-release
227 jfenwick 4439 sudo aptitude install python-sympy python-matplotlib python-scipy
228     sudo aptitude install python-pyproj python-gdal
229     \end{shellCode}
232     \begin{optionalstep}
233     If for some reason, you wish to rebuild the documentation, you would also need the following:
234     \begin{shellCode}
235     sudo aptitude install python-sphinx doxygen python-docutils texlive
236 sshaw 4555 sudo aptitude install zip texlive-latex-extra latex-xcolor
237 jfenwick 4439 \end{shellCode}
238     \end{optionalstep}
240 caltinay 4491 \noindent In the source directory execute the following (substitute squeeze or wheezy as appropriate for XXXX):
241 jfenwick 4439 \begin{shellCode}
242     scons -j1 options_file=scons/os/XXXX_options.py
243     \end{shellCode}
245 caltinay 4491 \noindent If you wish to test your build, you can use the following:
246 jfenwick 4439 \begin{shellCode}
247     scons -j1 py_tests options_file=scons/os/XXXX_options.py
248     \end{shellCode}
250     \subsection{Ubuntu}\label{sec:ubsrc}
252 jfenwick 4440 If you have not installed \texttt{aptitude}, then substitute \texttt{apt-get} in the following.
253     \begin{shellCode}
254     sudo aptitude install python-dev python-numpy libboost-python-dev libnetcdf-dev
255 sshaw 4551 sudo aptitude install scons lsb-release
256 jfenwick 4440 sudo aptitude install python-sympy python-matplotlib python-scipy
257     sudo aptitude install python-pyproj python-gdal
258     \end{shellCode}
261     \begin{optionalstep}
262     If for some reason, you wish to rebuild the documentation, you would also need the following:
263     \begin{shellCode}
264     sudo aptitude install python-sphinx doxygen python-docutils texlive
265 sshaw 4555 sudo aptitude install zip texlive-latex-extra latex-xcolor
266 jfenwick 4440 \end{shellCode}
267     \end{optionalstep}
269 caltinay 4491 \noindent In the source directory execute the following (substitute precise, quantal or raring as appropriate for XXXX):
270 jfenwick 4440 \begin{shellCode}
271     scons -j1 options_file=scons/os/XXXX_options.py
272     \end{shellCode}
274 caltinay 4491 \noindent If you wish to test your build, you can use the following:
275 jfenwick 4440 \begin{shellCode}
276     scons -j1 py_tests options_file=scons/os/XXXX_options.py
277     \end{shellCode}
281 jfenwick 4439 \subsection{OpenSuse}\label{sec:susesrc}
282 jfenwick 4384 These instructions were prepared using release $12.3$.
284 caltinay 4491 \noindent Install packages from the main distribution:
285 jfenwick 4384 \begin{shellCode}
286     sudo yast2 --install libboost_python1_49_0 python-devel python-numpy
287     sudo yast2 --install python-scipy python-sympy python-matplotlib libnetcdf_c++-devel
288     sudo yast2 --install gcc-c++ scons boost-devel netcdf-devel
289     \end{shellCode}
290     These will allow you to use most features except some parts of the \downunder inversion library.
291     If you wish to use those, you will need some additional packages [python-pyproj, python-gdal].
292     This can be done after Escript installation.
294     \begin{optionalstep}
295     Add \url{http://ftp.suse.de/pub/opensuse/repositories/Application:/Geo/openSUSE_12.3/}
296     to your repositories in \texttt{YaST}.
297     \begin{shellCode}
298     sudo yast2 --install python-pyproj, python-gdal
299     \end{shellCode}
300     \end{optionalstep}
302     Now to build escript itself.
303     In the escript source directory:
304     \begin{shellCode}
305     scons -j1 options_file=scons/os/opensuse12.3_options.py
306     \end{shellCode}
308 caltinay 4491 \noindent If you wish to test your build, you can use the following:
309 jfenwick 4384 \begin{shellCode}
310     scons -j1 py_tests options_file=scons/os/opensuse12.3_options.py
311     \end{shellCode}
313 caltinay 4491 \noindent Now go to Section~\ref{sec:cleanup} for cleanup.
314 jfenwick 4384
315 jfenwick 4439 \subsection{Centos}\label{sec:centossrc}
316 jfenwick 4384 These instructions were prepared using release $6.4$.
318 caltinay 4491 \noindent Install packages from the main distribution:
319 jfenwick 4384 \begin{shellCode}
320     yum install python-devel numpy scipy scons boost-devel
321     yum install python-matplotlib gcc-g++
322     yum install boost-python
323     \end{shellCode}
325     The above packages will allow you to use most features except saving and loading files in \texttt{netCDF}
326     format and the \downunder inversion library.
327     If you wish to use those features, you will need to install some additional packages.
328     NetCDF needs to be installed when you compile if you wish to use it.
329     \begin{optionalstep}
330 caltinay 4491 \noindent Add the \texttt{EPEL} repository.
331 jfenwick 4384 \begin{shellCode}
332     rpm -U http://download.fedoraproject.org/pub/epel/6/x86_64/epel-release-6-8.noarch.rpm
333     \end{shellCode}
335     \begin{shellCode}
336     yum install netcdf-devel sympy gdal-python
337     \end{shellCode}
338 caltinay 4491 \end{optionalstep}
339 jfenwick 4384
340 caltinay 4491 \noindent For some coordinate transformations, \downunder can also make use of the python interface to a tool called \texttt{proj}.
341 jfenwick 4384 There does not seem to be an obvious centos repository for this though.
342     If it turns out to be necessary for your particular application, the source can be downloaded.
344 caltinay 4491 \noindent Now to build escript itself.
345 jfenwick 4384 In the escript source directory:
346     \begin{shellCode}
347     scons -j1 options_file=scons/os/centos6.4_options.py
348     \end{shellCode}
350 caltinay 4491 \noindent If you wish to test your build, you can use the following:
351 jfenwick 4384 \begin{shellCode}
352     scons -j1 py_tests options_file=scons/os/centos6.4_options.py
353     \end{shellCode}
355 caltinay 4491 \noindent Now go to Section~\ref{sec:cleanup} for cleanup.
356 jfenwick 4384
357 jfenwick 4439 \subsection{Fedora}\label{sec:fedorasrc}
358 jfenwick 4384 These instructions were prepared using release $18$.
360 caltinay 4491 \noindent Install packages
361 jfenwick 4384 \begin{shellCode}
362     yum install netcdf-cxx-devel gcc-c++ scipy
363     yum install sympy scons pyproj gdal python-matplotlib
364     yum install boost-devel
365     \end{shellCode}
367 caltinay 4491 \noindent Now to build escript itself.
368 jfenwick 4384 In the escript source directory:
369     \begin{shellCode}
370     scons -j1 options_file=scons/os/fedora18_options.py
371     \end{shellCode}
373 caltinay 4491 \noindent If you wish to test your build, you can use the following:
374 jfenwick 4384 \begin{shellCode}
375     scons -j1 py_tests options_file=scons/os/fedora18_options.py
376     \end{shellCode}
378 caltinay 4491 \noindent Now go to Section~\ref{sec:cleanup} for cleanup.
379 jfenwick 4384
380 jfenwick 4439 \subsection{MacOS (macports)}\label{sec:macportsrc}
382 caltinay 4491 \begin{shellCode}
383     port install python27
384     port select --set python python27
385     port install scons
386     port install openmpi
387     port install py27-numpy
388     port install boost
389     port install py27-sympy
390     port select --set py-sympy py27-sympy
391     install py27-scipy
392     install py27-pyproj
393     install py27-gdal
394     install py27-netcdf4
395     install netcdf-cxx
396     \end{shellCode}
398     \begin{shellCode}
399     scons -j1 options_file=scons/os/macports_options.py
400     \end{shellCode}
403 jfenwick 4439 \subsection{MacOS (homebrew)}\label{sec:homebrewsrc}
405 caltinay 4491 Note that these steps add ``non-official'' packages.
406     You will also want to make sure that the homebrew Python is executed in preference to the system
407     Python\footnote{Putting \texttt{/usr/local/bin} at the front of your PATH is one way to do this.}.
409     \begin{shellCode}
410     brew install scons
411     brew install python
412     brew install boost
413     brew tap samueljohn/python
414     brew tap homebrew/science
415     pip install nose
416     brew install gfortran
417     brew install samueljohn/python/numpy
418     brew install scipy
419     brew install gdal
420     brew install openmpi
421     brew install matplotlib
422     brew install netcdf --enable-cxx-compat
423     \end{shellCode}
425     There do not appear to be formulae for \texttt{sympy} or \texttt{pyproj} so if you wish to use those features, then
426     you will need to install them separately.
429     \begin{shellCode}
430     scons -j1 options_file=scons/os/homebrew_options.py
431     \end{shellCode}
434 jfenwick 4439 \subsection{FreeBSD}\label{sec:freebsdsrc}
435 jfenwick 4450 The following was tested on the $9.1$ release of FreeBSD.
436     It passes the majority of tests but there is an issue related to some features in the inversion library.
437     The following set of installations ``works'' but is not guaranteed to be minimal\footnote{Depending on your needs you might be able to
438     get by with a smaller set of packages.}.
439 jfenwick 4439
440 jfenwick 4450 Install the following packages:
441     \begin{itemize}
442     \item subversion
443     \item scons
444     \item boost-python-libs
445     \item bash
446     \end{itemize}
447 jfenwick 4439
448 jfenwick 4450 Now install the following ports:
449     \begin{itemize}
450     \item science/py-scipy
451     \item science/py-netCDF4
452     \item math/sympy
453     \item graphics/py-pyproj
454     \item graphics/py-gdal
455     \item net/openmpi
456     \end{itemize}
457 jfenwick 4439
458 jfenwick 4450 You will need to add \texttt{/usr/local/mpi/openmpi/bin} to your path if you wish to build with MPI.
460     Next choose (or create) your options file.
461     In this case we have three prepared in the \texttt{scons/os} directory:
462     \begin{itemize}
463     \item \texttt{freebsd91_options.py}
464     \item \texttt{freebsd91_mpi_options.py} If you would like to use MPI.
465     \item \texttt{freebsd91_gcc46_options.py} Use this if you have managed to change compilers to gcc4.6 (and would like to use OpenMP).
466     \end{itemize}
468     In the escript source directory (where ZZZ is your options file):
469     \begin{shellCode}
470     scons -j1 options_file=ZZZ
471     \end{shellCode}
475 jfenwick 4439 \subsection{Other Systems / Custom Builds}\label{sec:othersrc}
477 jfenwick 4440 \escript has support for a number of optional packages.
478     Some, like \texttt{netcdf} need to be enabled at compile time, while others, such as \texttt{sympy} and the projection packages
479     used in \downunder are checked at run time.
480     For the second type, you can install them at any time (ensuring that python can find them) and they should work.
481     For the first type, you need to modify the options file and recompile with scons.
482     The rest of this section deals with this.
484     To avoid having to specify the options file each time you run scons, copy an existing \texttt{_options.py} file from the
485     \texttt{scons/} or \texttt{scons/os/} directories. Put the file in the \texttt{scons} directory and name
486     it \textit{yourmachinename}\texttt{_options.py}.\footnote{If the name
487     has - or other non-alpha characters, they must be replaced with underscores in the filename}.
488     For example: on a machine named toybox, the file would be \texttt{scons/toybox_options.py}.
490     Individual lines can be enabled/disabled, by removing or adding \# (the python comment character) to the beginning of the line.
491     For example, to enable OpenMP, change the line
492     \begin{verbatim}
493     #openmp = True
494     \end{verbatim}
495     to
496     \begin{verbatim}
497     openmp = True
498     \end{verbatim}.
500     If you are using libraries which are not installed in the standard places (or have different names) you will need to
501     change the relevant lines.
502 jfenwick 4673 A common need for this would be using a more recent version of the boost::python library.
503 jfenwick 4440
504     You can also change the compiler or the options passed to it by modifying the relevant lines.
506     \subsubsection*{MPI}
507 caltinay 4491 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}
508     configuration variable.
509     To disable MPI use, \verb|mpi = 'none'|.
510 jfenwick 4440 You will also need to ensure that the \texttt{mpi_prefix} and \texttt{mpi_libs} variables are uncommented and set correctly.
512     \subsubsection{Python3}
513     \escript works with \texttt{python3} but until recently, many distributions have not distributed python3 versions of their packages.
514     You can try it out though by modifying the following variables:
516     \begin{verbatim}
517     pythoncmd='python3'
518     \end{verbatim}
520     \begin{verbatim}
521     usepython3=True
522     \end{verbatim}
524     \begin{verbatim}
525     pythonlibname='whateveryourpython3libraryiscalled'
526     \end{verbatim}
531     \subsubsection{Testing}
532     As indicated earlier, you can test your build using \texttt{scons py_tests}.
533 jfenwick 4602 Note however, that some features like \texttt{netCDF} are optional for using \escript, the tests will report a failure if
534 jfenwick 4440 they are missing.
536 jfenwick 4384 \section{Cleaning up}
537     \label{sec:cleanup}
539     Once the build (and optional testing) is complete, you can remove everything except:
540     \begin{itemize}
541     \item bin
542     \item esys
543     \item lib
544     \item doc
545     \item CREDITS.TXT
546     \item README_LICENSE
547     \end{itemize}
548     The last two aren't strictly required for operation.
549     The \texttt{doc} directory is not required either but does contain examples of escript scripts.
551     You can run escript using \texttt{\textit{path_to_escript_files}/bin/run-escript}.
552     Where \texttt{\textit{path_to_escript_files}} is replaced with the real path.
554     \begin{optionalstep}
555     You can add the escript \texttt{bin} directory to your \texttt{PATH} variable.
556     The launcher will then take care of the rest of the environment.
557     \end{optionalstep}
559 jfenwick 4439 \section{Optional Extras}
560 jfenwick 4440
561     Some other packages which might be useful include:
562     \begin{itemize}
563     \item support for silo format (install the relevant libraries and enable them in the options file).
564     \item Visit --- visualisation package. Can be used independently but our \texttt{weipa} library can make a Visit
565     plug-in to allow direct visualisation of escript files.
566     \item gmsh --- meshing software used by our \texttt{pycad} library.
567     \item mayavi --- another visualisation tool.
568     \end{itemize}
571 jfenwick 4384 %Need a better title but this is stuff like visit and silo (for non-debian distros)
572 jfenwick 4439 %Perhaps - optional extras
573 jfenwick 4384

  ViewVC Help
Powered by ViewVC 1.1.26