Contents of /branches/doubleplusgood/doc/install/srclinux.tex

Revision 4345 - (show annotations)
Fri Mar 29 07:09:41 2013 UTC (6 years ago) by jfenwick
File MIME type: application/x-tex
File size: 12095 byte(s)
Spelling fixes

 1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 2 % Copyright (c) 2003-2013 by University of Queensland 3 4 % 5 % Primary Business: Queensland, Australia 6 % Licensed under the Open Software License version 3.0 7 8 % 9 % Development until 2012 by Earth Systems Science Computational Center (ESSCC) 10 % Development since 2012 by School of Earth Sciences 11 % 12 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 13 14 \section{Installing from source for \linux} 15 \label{sec:srclinux} 16 17 \subsection{Dependencies} 18 19 The following instructions assume you are running the \file{bash} shell. 20 Comments are indicated with \# characters. 21 Make sure you have the following installed: 22 \begin{itemize} 23 \item \file{g++} and associated tools. 24 \item \file{make} 25 % I suspect that these are only needed by VTK and if we aren't using it anymore they could be removed 26 % \item \file{libXext.so}\footnote{In Debian this is in the libXext-dev package.} 27 % \item \file{libxt.so}\footnote{In Debian this is in the libxt-dev package.} 28 \end{itemize} 29 30 \noindent To compile matplotlib you will also need the following\footnote{For 31 Debian and Ubuntu users, installing \file{libfreetype6-dev} and 32 \file{libpng-dev} will be sufficient.} (if your distribution separates 33 development files, make sure to get the development packages): 34 \begin{itemize} 35 \item \file{freetype2} 36 \item \file{zlib} 37 \item \file{libpng} 38 \end{itemize} 39 40 \noindent In order to fully test the installation using the unit tests you also 41 need\footnote{On Debian and Ubuntu this is packaged as \file{libcppunit-dev}}: 42 \begin{itemize} 43 \item \file{cppunit} 44 \end{itemize} 45 However, a large number of tests will work without it. 46 47 \subsection{Preliminaries} 48 \label{sec:prelim} 49 You will also need a copy of the \esfinley source code. 50 If you retrieved the source using subversion, don't forget that one can use the export command instead of checkout to get a smaller copy. 51 For additional visualization functionality see Section~\ref{sec:addfunc}. 52 53 These instructions will produce the following directory structure: 54 \begin{itemize} 55 \item[] \file{stand} \begin{itemize} 56 \item[] \file{escript.d} 57 \item[] \file{pkg} 58 \item[] \file{pkg_src} 59 \item[] \file{build} 60 \item[] \file{doc} 61 \end{itemize} 62 \end{itemize} 63 64 Before you start copy the \esfinley source into the \file{escript.d} directory. 65 The following instructions refer to software versions in the \file{escript-support-3-src} bundle. 66 If you download your own versions of those packages substitute their version numbers and names as appropriate. 67 There are a number of uses of the \file{make} command in the following instructions. 68 If your computer has multiple cores/processors you can speed up the compilation process by adding -j 2 after the make command. 69 For example to use all processors on a computer with 4 cores: 70 \begin{shellCode} 71 make 72 \end{shellCode} 73 becomes 74 \begin{shellCode} 75 make -j 4 76 \end{shellCode} 77 78 \begin{shellCode} 79 mkdir stand 80 cd stand 81 mkdir build doc pkg pkg_src 82 export PKG_ROOT=$(pwd)/pkg 83 \end{shellCode} 84 85 \subsection{Building the dependencies} 86 87 Copy the compressed sources for the packages into \file{stand/pkg_src}. 88 If you are using the support bundles, decompress them in the stand directory: 89 \begin{shellCode} 90 tar -xjf escript-support-3-src.tar.bz2 91 \end{shellCode} 92 93 Copy documentation files into \file{doc} then unpack the archives: 94 95 \begin{shellCode} 96 cd build 97 tar -jxf ../pkg_src/Python-2.6.2.tar.bz2 98 tar -jxf ../pkg_src/boost_1_39_0.tar.bz2 99 tar -zxf ../pkg_src/scons-1.2.0.tar.gz 100 tar -zxf ../pkg_src/numpy-1.3.0.tar.gz 101 tar -zxf ../pkg_src/netcdf-4.0.tar.gz 102 tar -zxf ../pkg_src/matplotlib-0.98.5.3.tar.gz 103 \end{shellCode} 104 105 \begin{itemize} 106 107 \item Build Python: 108 \begin{shellCode} 109 cd Python* 110 ./configure --prefix=$PKG_ROOT/python-2.6.2 --enable-shared 2>&1 \ 111 | tee tt.configure.out 112 make 113 make install 2>&1 | tee tt.make.out 114 115 cd .. 116 117 export PATH=$PKG_ROOT/python/bin:$PATH 118 export PYTHONHOME=$PKG_ROOT/python 119 export LD_LIBRARY_PATH=$PKG_ROOT/python/lib:$LD_LIBRARY_PATH 120 121 pushd ../pkg 122 ln -s python-2.6.2/ python 123 popd 124 \end{shellCode} 125 126 Run the new python executable to make sure it works. 127 128 \item Now build NumPy: 129 \begin{shellCode} 130 cd numpy-1.3.0 131 python setup.py build 132 python setup.py install --prefix$PKG_ROOT/numpy-1.3.0 133 cd .. 134 pushd ../pkg 135 ln -s numpy-1.3.0 numpy 136 popd 137 export PYTHONPATH=$PKG_ROOT/numpy/lib/python2.6/site-packages:$PYTHONPATH 138 \end{shellCode} 139 140 % \begin{shellCode} 141 % cd numarray-1.5.2 142 % 143 % python setup.py install \ 144 % --gencode --install-lib=$PKG_ROOT/numarray-1.5.2/lib \ 145 % --install-headers=$PKG_ROOT=$PKG_ROOT/numarray-1.5.2/include/numarray \ 146 % 2>&1 | tee tt.install.out 147 % 148 % 149 % export PYTHONPATH=$PKG_ROOT/numarray/lib:$PYTHONPATH 150 % cd .. 151 % pushd ../pkg 152 % ln -s numarray-1.5.2 numarray 153 % popd 154 % \end{shellCode} 155 156 \item Next build scons: 157 \begin{shellCode} 158 cd scons-1.2.0 159 python setup.py install --prefix=$PKG_ROOT/scons-1.2.0 160 161 export PATH=$PKG_ROOT/scons/bin:$PATH 162 cd .. 163 pushd ../pkg 164 ln -s scons-1.2.0 scons 165 popd 166 \end{shellCode} 167 168 \item The Boost libraries...: 169 \begin{shellCode} 170 pushd ../pkg 171 mkdir boost_1_39_0 172 ln -s boost_1_39_0 boost 173 popd 174 cd boost_1_39_0 175 ./bootstrap.sh --with-libraries=python --prefix=$PKG_ROOT/boost 176 ./bjam 177 ./bjam install --prefix=$PKG_ROOT/boost --libdir=$PKG_ROOT/boost/lib 178 export LD_LIBRARY_PATH=$PKG_ROOT/boost/lib:$LD_LIBRARY_PATH 179 cd .. 180 pushd ../pkg/boost/lib/ 181 ln *.so.* libboost_python.so 182 popd 183 \end{shellCode} 184 185 \item ...and netCDF: 186 \begin{shellCode} 187 cd netcdf-4.0 188 CFLAGS="-O2 -fPIC -Df2cFortran" CXXFLAGS="-O2 -fPIC -Df2cFortran" \ 189 FFLAGS="-O2 -fPIC -Df2cFortran" FCFLAGS="-O2 -fPIC -Df2cFortran" \ 190 ./configure --prefix=$PKG_ROOT/netcdf-4.0 191 192 make 193 make install 194 195 export LD_LIBRARY_PATH=$PKG_ROOT/netcdf/lib:$LD_LIBRARY_PATH 196 cd .. 197 pushd ../pkg 198 ln -s netcdf-4.0 netcdf 199 popd 200 \end{shellCode} 201 202 \item Finally matplotlib: 203 \begin{shellCode} 204 cd matplotlib-0.98.5.3 205 python setup.py build 206 python setup.py install --prefix=$PKG_ROOT/matplotlib-0.98.5.3 207 cd .. 208 pushd ../pkg 209 ln -s matplotlib-0.98.5.3 matplotlib 210 popd 211 cd .. 212 \end{shellCode} 213 214 \end{itemize} 215 216 % \subsection{VTK support} 217 % VTK is only required for pyvisi. To build it you need CMake and Mesa. 218 % The packages can be downloaded independently or in the \file{escript-support-visi-3-src}. 219 % If you will not be using pyvisi, then skip to \Sec{sec:compileescriptlinux} 220 % 221 % Copy the compressed sources for the packages into \file{stand/pkg_src}. 222 % If you are using the support bundles, decompress them in the stand directory. 223 % \begin{shellCode} 224 % tar -xjf escript-support-visi-3-src.tar.bz2 225 % \end{shellCode} 226 % 227 % \begin{shellCode} 228 % cd build 229 % tar -jxf ../pkg_src/MesaLib-7.2.tar.bz2 230 % tar -zxf ../pkg_src/vtk-5.2.1.tar.gz 231 % tar -zxf ../pkg_src/vtkdata-5.2.1.tar.gz 232 % tar -zxf ../pkg_src/cmake-2.6.3.tar.gz 233 % \end{shellCode} 234 % 235 % \begin{itemize} 236 % 237 % \item Build CMake: 238 % \begin{shellCode} 239 % cd cmake-2.6.3 240 % ./configure --prefix=$PKG_ROOT/cmake-2.6.3 2>&1 | tee tt.configure 241 % make 242 % make install 243 % 244 % export PATH=$PKG_ROOT/cmake/bin:$PATH 245 % cd .. 246 % pushd ../pkg 247 % ln -s cmake-2.6.3 cmake 248 % popd 249 % \end{shellCode} 250 % 251 % \item Build Mesa: 252 % \begin{shellCode} 253 % cd Mesa-7.2 254 % ./configure --prefix=$PKG_ROOT/mesa-7.2 --enable-gl-osmesa --with-driver=xlib 255 % 256 % make 257 % make install 258 % 259 % export LD_LIBRARY_PATH=$PKG_ROOT/mesa/lib:$LD_LIBRARY_PATH 260 % cd .. 261 % pushd ../pkg 262 % ln -s mesa-7.2 mesa 263 % popd 264 % \end{shellCode} 265 % These instructions do not compile MesaDemos or GLUT. 266 % If you need to check if Mesa compiled correctly, then the demos are a good test. 267 % 268 % \item Finally, build VTK: 269 % \begin{shellCode} 270 % cd VTK 271 % cmake . 272 % \end{shellCode} 273 % 274 % Now edit the \file{CMakeCache.txt} file and make the following changes. 275 % Where .... appears please replace it with the absolute path to the pkg directory. 276 % For example, replace \file{CMAKE_INSTALL_PREFIX:PATH=..../vtk-5.2.1} with 277 % \file{CMAKE_INSTALL_PREFIX:PATH=/home/bob/stand/pkg/vtk-5.2.1} 278 % (Search for the text before the =). 279 % \begin{shellCode} 280 % BUILD_EXAMPLES:BOOL=OFF 281 % BUILD_SHARED_LIBS:BOOL=ON 282 % CMAKE_INSTALL_PREFIX:PATH=..../vtk-5.2.1 283 % CMAKE_VERBOSE_MAKEFILE:BOOL=TRUE 284 % VTK_OPENGL_HAS_OSMESA:BOOL=TRUE 285 % VTK_USE_64BIT_IDS:BOOL=ON 286 % VTK_WRAP_PYTHON:BOOL=ON 287 % VTK_USE_MANGLED_MESA:BOOL=OFF 288 % \end{shellCode} 289 % 290 % Now rerun cmake (it won't work but it adds some variables you need). 291 % 292 % \begin{shellCode} 293 % cmake . 294 % \end{shellCode} 295 % 296 % Edit \file{CMakeCache.txt} and change the following variables: 297 % 298 % \begin{shellCode} 299 % VTK_USE_OFFSCREEN:BOOL=ON 300 % VTK_USE_TK:BOOL=OFF 301 % OSMESA_INCLUDE_DIR:PATH=..../mesa/include 302 % OSMESA_LIBRARY:FILEPATH=..../mesa/lib/libOSMesa.so 303 % PYTHON_INCLUDE_PATH:PATH=..../python/include/python2.6 304 % PYTHON_LIBRARY:FILEPATH=..../python/lib/libpython2.6.so 305 % OPENGL_INCLUDE_DIR:PATH=..../mesa/include 306 % OPENGL_gl_LIBRARY:FILEPATH=..../mesa/lib/libGL.so 307 % \end{shellCode} 308 % 309 % The following steps will take a while so grab a coffee while it compiles. 310 % \begin{shellCode} 311 % cmake . 312 % make 313 % chmod +w Utilities/vtktiff/tif_fax3sm.c 314 % make install 315 % 316 % cd ../../pkg 317 % ln -s vtk-5.2.1 vtk 318 % cd .. 319 % \end{shellCode} 320 % 321 % \end{itemize} 322 323 \subsection{Compiling escript}\label{sec:compileescriptlinux} 324 325 Change to the directory containing your escript source (\file{stand/escript.d}), then: 326 327 \begin{shellCode} 328 cd escript.d/scons 329 cp TEMPLATE_linux.py YourMachineName_options.py 330 331 echo$PKG_ROOT 332 \end{shellCode} 333 Where \texttt{YourMachineName} is the name of your computer as returned by the hostname command. 334 If the name contains non-alphanumeric characters, then you will need to replace them with underscores. 335 For example the options file for \texttt{bob-desktop} would be named \file{bob_desktop_options.py}. 336 If you wish to build with OpenMP, MPI or configure other aspects of the system take a quick look at Section~\ref{sec:compilesrc}. 337 338 339 You will need to edit your options file and specify where to find boost and netcdf. 340 (replace \file{x/stand} with the path to \file{stand}) 341 342 \begin{python} 343 #boost_prefix = '/usr/local' 344 \end{python} 345 346 should be 347 \begin{python} 348 boost_prefix = ['x/stand/pkg/boost/include/boost-1_39/', 'x/stand/pkg/boost/lib/'] 349 \end{python} 350 351 \begin{python} 352 #netcdf = True 353 \end{python} 354 355 should be 356 \begin{python} 357 netcdf = True 358 \end{python} 359 360 \begin{python} 361 #netcdf_prefix = '/usr/local' 362 \end{python} 363 364 should be \begin{python} 365 netcdf_prefix = ['x/stand/pkg/netcdf/include/', 366 'x/stand/pkg/netcdf/lib/'] 367 \end{python} 368 369 % 370 % Edit the options file and put the value of PKG_ROOT between the quotes in the PKG_ROOT= line. 371 % For example: 372 % \begin{shellCode} 373 % PKG_ROOT="/home/bob/stand/pkg" 374 % \end{shellCode} 375 376 \begin{shellCode} 377 cd ../bin 378 \end{shellCode} 379 380 Modify the STANDALONE line of \file{run-escript} to read: 381 382 STANDALONE=1 383 384 Start a new terminal and go to the \file{stand} directory. 385 386 \begin{shellCode} 387 export PATH=$(pwd)/pkg/scons/bin:$PATH 388 cd escript.d 389 eval \$(bin/run-escript -e) 390 scons 391 \end{shellCode} 392 393 If you wish to test your build, then you can do the following. 394 Note this may take a while if you have a slow processor and/or less than 1GB of RAM. 395 \begin{shellCode} 396 scons py_tests 397 \end{shellCode} 398 (If you have cppunit installed you can run additional tests using \texttt{scons all_tests}. 399 400 \subsection{Cleaning up} 401 Once you are satisfied, the \file{escript.d/build} and \file{stand/build} directories can be removed. 402 403 If you \emph{really} want to save space and do not wish to be able to edit or recompile \esfinley, you can remove the following: 404 \begin{itemize} 405 \item From the \file{escript.d} directory:\begin{itemize} 406 \item Everything except: \file{bin}, \file{include}, \file{lib}, \file{esys}, 407 \file{README_LICENSE}. 408 \item Hidden files, which can be removed using 409 \begin{shellCode} 410 find . -name '.?*' | xargs rm -rf 411 \end{shellCode} 412 in the \file{escript.d} directory. 413 \end{itemize} 414 \item from the \file{pkg} directory: 415 \begin{itemize} 416 \item \file{scons}, \file{scons-1.2.0} 417 \end{itemize} 418 \item \file{package\_src}\footnote{Do not remove this if you intend to redistribute.}. 419 \end{itemize} 420 421 Please note that removing all these files may make it more difficult for us to diagnose problems. 422 423