doc/install/srclinux.tex


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% Copyright (c) 2003-2008 by University of Queensland
% Earth Systems Science Computational Center (ESSCC)
% http://www.uq.edu.au/esscc
%
% Primary Business: Queensland, Australia
% Licensed under the Open Software License version 3.0
% http://www.opensource.org/licenses/osl-3.0.php
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Installing from source for \linux}
\label{sec:srclinux}
The following instructions assume you are running the \filename{bash} shell.
Comments are indicated with \# characters.

Make sure you have the following installed:
\begin{itemize}
 \item \filename{g++} and associated tools.
\item \filename{make}
\item \filename{libXext.so}\footnote{In Debian this is in the libXext-dev package.}
\item \filename{libxt.so}\footnote{In Debian this is in the libxt-dev package.}
\end{itemize}

You will also need a copy of the \esfinley source code.
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.
For additional visualisation functionality see Section~\ref{sec:linaddfunc}.

These instructions will produce the following structure:
\begin{itemize}
\item \filename{stand}: \begin{itemize}
 \item \filename{escript.d}
\item \filename{packages}
\item \filename{package_src}
\item \filename{build}
\item \filename{doc}
  \end{itemize}
\end{itemize}

The build directory can be removed when you are finished.

\begin{shellCode}
mkdir stand
cd stand
export PKG_ROOT=$(pwd)/packages
\end{shellCode}

Copy compressed source bundles into \filename{stand/package_src}.
Copy documentation files into \filename{doc}.

\begin{shellCode}
mkdir packages
mkdir build
cd build
tar -jxf ../package_src/Python-2.6.1.tar.bz2
tar -jxf ../package_src/boost_1_37_0.tar.bz2
tar -jxf ../package_src/MesaLib-7.2.tar.bz2
tar -zxf ../package_src/netcdf-4.0.tar.gz
tar -zxf ../package_src/vtk-5.2.1.tar.gz
tar -zxf ../package_src/vtkdata-5.2.1.tar.gz
tar -zxf ../package_src/cmake-2.6.3.tar.gz
tar -zxf ../package_src/scons-1.2.0.tar.gz
tar -zxf ../package_src/numpy-1.3.0.tar.gz
\end{shellCode}

Build python.
\begin{shellCode}
cd Python*
./configure --prefix=$PKG_ROOT/python-2.6.1 --enable-shared 2>&1 \
  | tee tt.configure.out
make install 2>&1 | tee tt.make.out

cd ..

export PATH=$PKG_ROOT/python/bin:$PATH
export PYTHONHOME=$PKG_ROOT/python
export LD_LIBRARY_PATH=$PKG_ROOT/python/lib:$LD_LIBRARY_PATH

pushd ../packages
ln -s python-2.6.1/ python
popd

\end{shellCode}

Run python to make sure it works.
Now build numpy.

\begin{shellCode}
cd numpy-1.3.0
python setup.py build
python setup.py install --prefix $PKG_ROOT/numpy-1.3.0
cd ..
pushd ../packages
ln -s numpy-1.3.0 numpy
popd
export PYTHONPATH=$PKG_ROOT/numpy/lib/python2.6/site-packages:$PYTHONPATH
\end{shellCode}


% \begin{shellCode}
% cd numarray-1.5.2
% 
% python setup.py install \
%  --gencode --install-lib=$PKG_ROOT/numarray-1.5.2/lib \
%  --install-headers=$PKG_ROOT=$PKG_ROOT/numarray-1.5.2/include/numarray \ 
%    2>&1 | tee tt.install.out
% 
% 
% export PYTHONPATH=$PKG_ROOT/numarray/lib:$PYTHONPATH
% cd ..
% pushd ../packages
% ln -s numarray-1.5.2 numarray
% popd
% \end{shellCode}

Now we build scons.
\begin{shellCode}
cd scons-1.2.0
python setup.py install --prefix=$PKG_ROOT/scons-1.2.0

export PATH=$PKG_ROOT/scons/bin:$PATH
cd ..
pushd ../packages
ln -s scons-1.2.0 scons
popd
\end{shellCode}

...Boost libraries ...
\begin{shellCode}
cd boost_1_37_0

./configure --prefix=$PKG_ROOT/boost_1_37_0 --with-python-root=$PKG_ROOT/python \
  --with-python-version=2.6 --with-libraries=python

make
make install
ln -s $PKG_ROOT/boost_1_37_0 $PKG_ROOT/boost
export LD_LIBRARY_PATH=$PKG_ROOT/boost/lib:$LD_LIBRARY_PATH
cd ..
pushd ../packages
ln -s boost_1_37_0 boost
popd
\end{shellCode}

... and netcdf.
\begin{shellCode}
cd netcdf-4.0
CFLAGS="-O2 -fPIC -Df2cFortran" CXXFLAGS="-O2 -fPIC -Df2cFortran" \
FFLAGS="-O2 -fPIC -Df2cFortran" FCFLAGS="-O2 -fPIC -Df2cFortran" \
./configure --prefix=$PKG_ROOT/netcdf-4.0

make -j2
make install

export LD_LIBRARY_PATH=$PKG_ROOT/netcdf/lib:$LD_LIBRARY_PATH
cd ..
pushd ../packages
ln -s netcdf-4.0 netcdf
popd
\end{shellCode}

CMake and Mesa are required for VTK. 
\begin{shellCode}
cd cmake-2.6.3
./configure --prefix=$PKG_ROOT/cmake-2.6.3 2>&1 | tee tt.configure
make -j 4
make install

export PATH=$PKG_ROOT/cmake/bin:$PATH
cd ..
pushd ../packages
ln -s cmake-2.6.3 cmake
popd
\end{shellCode}

These instructions do not compile MesaDemos or GLUT.
If you need to check if Mesa compiled correctly, then the demos are a good test.
\begin{shellCode}
cd Mesa-7.2
./configure --prefix=$PKG_ROOT/mesa-7.2 --enable-gl-osmesa --with-driver=xlib

make -j 4
make install

export LD_LIBRARY_PATH=$PKG_ROOT/mesa:$LD_LIBRARY_PATH
cd ..
pushd ../packages
ln -s mesa-7.2 mesa
popd
\end{shellCode}

\begin{shellCode}
cd VTK
cmake .

#Edit the CMakeCache.txt file and make the following changes: 
#(Please replace .... with an absolute path to the stand directory)
#The text before the = is the text to search for.
#For example, 
#   BUILD_SHARED_LIBS:BOOL=OFF
# should be changed to read
#   BUILD_SHARED_LIBS:BOOL=ON
#-----------------

BUILD_EXAMPLES:BOOL=OFF
BUILD_SHARED_LIBS:BOOL=ON

CMAKE_INSTALL_PREFIX:PATH=..../stand/packages/vtk-5.2.1
CMAKE_VERBOSE_MAKEFILE:BOOL=TRUE

#check PYTHON_EXECUTABLE is correct.
#but it seems to be when I went through these steps

VTK_OPENGL_HAS_OSMESA:BOOL=TRUE
VTK_USE_64BIT_IDS:BOOL=ON
# That last one is marked as "May cause some bugs" in the original instructions

VTK_WRAP_PYTHON:BOOL=ON
VTK_USE_MANGLED_MESA:BOOL=OFF

VTK_USE_OFFSCREEN:BOOL=ON
#--------------------

cmake .
#It won't work but it will put some variables in that you need.

#Edit CMakeCache again and make the following changes

#----------------

VTK_USE_TK:BOOL=OFF

OSMESA_INCLUDE_DIR:PATH=..../stand/packages/mesa/include

OSMESA_LIBRARY:FILEPATH=..../stand/packages/mesa/lib/libOSMesa.so

PYTHON_INCLUDE_PATH:PATH=..../stand/packages/python/include/python2.6

PYTHON_LIBRARY:FILEPATH=..../stand/packages/python/lib/libpython2.6.so

OPENGL_INCLUDE_DIR:PATH=..../stand/packages/mesa/include

OPENGL_gl_LIBRARY:FILEPATH=..../stand/packages/mesa/lib/libGL.so

#----------------

cmake .

chmod +w Utilities/vtktiff/tif_fax3sm.c

make
make install


cd ../../packages
ln -s vtk-5.2.1 vtk
cd ..
\end{shellCode}

Now copy the \esfinley source into an \filename{escript.d} directory in \filename{stand}.

\subsection{Compiling escript}\label{sec:compileescriptlinux}

Change to the directory containing your escript source (\filename{escript.d}), then:

\begin{shellCode}
cd scons
cp linux_options_example.py YourMachineName_options.py

#edit the options file and make the following changes:
#-----------------------------------------------------------------
declare a PKG_ROOT variable at the top of the file eg:
PKG_ROOT="/home/jfenwick/stand/packages"

python_path     = PKG_ROOT+"python/include/python2.6"
python_lib_path     = PKG_ROOT+"python/lib"
python_libs     = "python2.6"

boost_path      = PKG_ROOT+"boost/include/boost-1_37"
boost_lib_path      = PKG_ROOT+"boost/lib"
boost_libs      = ["boost_python-gcc43-mt"]
# You could simlink the boost python library to give a shorter 
# name but it's not worth it

usevtk      = "yes"
#-------------------------------------------------------------------

cd ..

#Modify bin/escript
#--------------------------------------------------
STANDALONE=1

#Check to make sure the paths in the if [ $STANDALONE == 1 ]
#block are correct

#-----------------------------------------------------------------

#start a new terminal
cd stand
export PATH=$(pwd)/packages/scons/bin:$PATH
cd escript.d
eval $(bin/escript -e)
scons
\end{shellCode}

If you wish to test your build, then you can do the following. 
Note this may take a while if you have a slow processor and/or less than 1Gb of RAM.
\begin{shellCode}
scons all_tests
\end{shellCode}

\subsection{Cleaning up}
Once you are satisfied, the \filename{escript.d/build} and \filename{\$PKG_ROOT/build} directories can be removed.

If you \emph{really} want to save space and do not wish to be able to edit or recompile escript, you can remove the following:
\begin{itemize}
 \item From the \filename{escript.d} directory:\begin{itemize}
\item Everything except: \filename{bin}, \filename{include}, \filename{lib}, \filename{esys},
\filename{README_LICENSE}.
\item Hidden files, which can be removed using
\begin{shellCode}
find . -name .?* | xargs rm -rf
\end{shellCode}
in the \filename{escript.d} directory.
\end{itemize}
\item from the \filename{packages} directory:
\begin{itemize}
\item  \filename{scons}, \filename{scons-1.2.0}, \filename{cmake-2.6.3} and \filename{cmake}
\end{itemize}
\item \filename{package\_src}\footnote{Do not remove this if you intend to redistribute.}.
\end{itemize}

Please note that removing all these files may make it more difficult for us to diagnose problems.


\section{Additional Functionality}\label{sec:linaddfunc}
To perform visualisations you will need some additional tools.
Since these do not need to be linked with any of the packages above, you can install versions available for your
system, or build them from source.
\begin{itemize}
\item \filename{ppmtompeg} and \filename{jpegtopnm} from the \filename{netpbm} suite. - To build from source 
you would also need \filename{libjpeg} and its headers as well as \filename{libpng}\footnote{libpng requires zlib to build} and its headers.
\item A tool to visualise VTK files. For example Mayavi or Visit.
\end{itemize}
1
2	%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3	%
4	% Copyright (c) 2003-2008 by University of Queensland
5	% Earth Systems Science Computational Center (ESSCC)
6	% http://www.uq.edu.au/esscc
7	%
8	% Primary Business: Queensland, Australia
9	% Licensed under the Open Software License version 3.0
10	% http://www.opensource.org/licenses/osl-3.0.php
11	%
12	%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
13
14	\section{Installing from source for \linux}
15	\label{sec:srclinux}
16	The following instructions assume you are running the \filename{bash} shell.
17	Comments are indicated with \# characters.
18
19	Make sure you have the following installed:
20	\begin{itemize}
21	\item \filename{g++} and associated tools.
22	\item \filename{make}
23	\item \filename{libXext.so}\footnote{In Debian this is in the libXext-dev package.}
24	\item \filename{libxt.so}\footnote{In Debian this is in the libxt-dev package.}
25	\end{itemize}
26
27	You will also need a copy of the \esfinley source code.
28	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.
29	For additional visualisation functionality see Section~\ref{sec:linaddfunc}.
30
31	These instructions will produce the following structure:
32	\begin{itemize}
33	\item \filename{stand}: \begin{itemize}
34	\item \filename{escript.d}
35	\item \filename{packages}
36	\item \filename{package_src}
37	\item \filename{build}
38	\item \filename{doc}
39	\end{itemize}
40	\end{itemize}
41
42	The build directory can be removed when you are finished.
43
44	\begin{shellCode}
45	mkdir stand
46	cd stand
47	export PKG_ROOT=$(pwd)/packages
48	\end{shellCode}
49
50	Copy compressed source bundles into \filename{stand/package_src}.
51	Copy documentation files into \filename{doc}.
52
53	\begin{shellCode}
54	mkdir packages
55	mkdir build
56	cd build
57	tar -jxf ../package_src/Python-2.6.1.tar.bz2
58	tar -jxf ../package_src/boost_1_37_0.tar.bz2
59	tar -jxf ../package_src/MesaLib-7.2.tar.bz2
60	tar -zxf ../package_src/netcdf-4.0.tar.gz
61	tar -zxf ../package_src/vtk-5.2.1.tar.gz
62	tar -zxf ../package_src/vtkdata-5.2.1.tar.gz
63	tar -zxf ../package_src/cmake-2.6.3.tar.gz
64	tar -zxf ../package_src/scons-1.2.0.tar.gz
65	tar -zxf ../package_src/numpy-1.3.0.tar.gz
66	\end{shellCode}
67
68	Build python.
69	\begin{shellCode}
70	cd Python*
71	./configure --prefix=$PKG_ROOT/python-2.6.1 --enable-shared 2>&1 \
72	\| tee tt.configure.out
73	make install 2>&1 \| tee tt.make.out
74
75	cd ..
76
77	export PATH=$PKG_ROOT/python/bin:$PATH
78	export PYTHONHOME=$PKG_ROOT/python
79	export LD_LIBRARY_PATH=$PKG_ROOT/python/lib:$LD_LIBRARY_PATH
80
81	pushd ../packages
82	ln -s python-2.6.1/ python
83	popd
84
85	\end{shellCode}
86
87	Run python to make sure it works.
88	Now build numpy.
89
90	\begin{shellCode}
91	cd numpy-1.3.0
92	python setup.py build
93	python setup.py install --prefix $PKG_ROOT/numpy-1.3.0
94	cd ..
95	pushd ../packages
96	ln -s numpy-1.3.0 numpy
97	popd
98	export PYTHONPATH=$PKG_ROOT/numpy/lib/python2.6/site-packages:$PYTHONPATH
99	\end{shellCode}
100
101
102	% \begin{shellCode}
103	% cd numarray-1.5.2
104	%
105	% python setup.py install \
106	% --gencode --install-lib=$PKG_ROOT/numarray-1.5.2/lib \
107	% --install-headers=$PKG_ROOT=$PKG_ROOT/numarray-1.5.2/include/numarray \
108	% 2>&1 \| tee tt.install.out
109	%
110	%
111	% export PYTHONPATH=$PKG_ROOT/numarray/lib:$PYTHONPATH
112	% cd ..
113	% pushd ../packages
114	% ln -s numarray-1.5.2 numarray
115	% popd
116	% \end{shellCode}
117
118	Now we build scons.
119	\begin{shellCode}
120	cd scons-1.2.0
121	python setup.py install --prefix=$PKG_ROOT/scons-1.2.0
122
123	export PATH=$PKG_ROOT/scons/bin:$PATH
124	cd ..
125	pushd ../packages
126	ln -s scons-1.2.0 scons
127	popd
128	\end{shellCode}
129
130	...Boost libraries ...
131	\begin{shellCode}
132	cd boost_1_37_0
133
134	./configure --prefix=$PKG_ROOT/boost_1_37_0 --with-python-root=$PKG_ROOT/python \
135	--with-python-version=2.6 --with-libraries=python
136
137	make
138	make install
139	ln -s $PKG_ROOT/boost_1_37_0 $PKG_ROOT/boost
140	export LD_LIBRARY_PATH=$PKG_ROOT/boost/lib:$LD_LIBRARY_PATH
141	cd ..
142	pushd ../packages
143	ln -s boost_1_37_0 boost
144	popd
145	\end{shellCode}
146
147	... and netcdf.
148	\begin{shellCode}
149	cd netcdf-4.0
150	CFLAGS="-O2 -fPIC -Df2cFortran" CXXFLAGS="-O2 -fPIC -Df2cFortran" \
151	FFLAGS="-O2 -fPIC -Df2cFortran" FCFLAGS="-O2 -fPIC -Df2cFortran" \
152	./configure --prefix=$PKG_ROOT/netcdf-4.0
153
154	make -j2
155	make install
156
157	export LD_LIBRARY_PATH=$PKG_ROOT/netcdf/lib:$LD_LIBRARY_PATH
158	cd ..
159	pushd ../packages
160	ln -s netcdf-4.0 netcdf
161	popd
162	\end{shellCode}
163
164	CMake and Mesa are required for VTK.
165	\begin{shellCode}
166	cd cmake-2.6.3
167	./configure --prefix=$PKG_ROOT/cmake-2.6.3 2>&1 \| tee tt.configure
168	make -j 4
169	make install
170
171	export PATH=$PKG_ROOT/cmake/bin:$PATH
172	cd ..
173	pushd ../packages
174	ln -s cmake-2.6.3 cmake
175	popd
176	\end{shellCode}
177
178	These instructions do not compile MesaDemos or GLUT.
179	If you need to check if Mesa compiled correctly, then the demos are a good test.
180	\begin{shellCode}
181	cd Mesa-7.2
182	./configure --prefix=$PKG_ROOT/mesa-7.2 --enable-gl-osmesa --with-driver=xlib
183
184	make -j 4
185	make install
186
187	export LD_LIBRARY_PATH=$PKG_ROOT/mesa:$LD_LIBRARY_PATH
188	cd ..
189	pushd ../packages
190	ln -s mesa-7.2 mesa
191	popd
192	\end{shellCode}
193
194	\begin{shellCode}
195	cd VTK
196	cmake .
197
198	#Edit the CMakeCache.txt file and make the following changes:
199	#(Please replace .... with an absolute path to the stand directory)
200	#The text before the = is the text to search for.
201	#For example,
202	# BUILD_SHARED_LIBS:BOOL=OFF
203	# should be changed to read
204	# BUILD_SHARED_LIBS:BOOL=ON
205	#-----------------
206
207	BUILD_EXAMPLES:BOOL=OFF
208	BUILD_SHARED_LIBS:BOOL=ON
209
210	CMAKE_INSTALL_PREFIX:PATH=..../stand/packages/vtk-5.2.1
211	CMAKE_VERBOSE_MAKEFILE:BOOL=TRUE
212
213	#check PYTHON_EXECUTABLE is correct.
214	#but it seems to be when I went through these steps
215
216	VTK_OPENGL_HAS_OSMESA:BOOL=TRUE
217	VTK_USE_64BIT_IDS:BOOL=ON
218	# That last one is marked as "May cause some bugs" in the original instructions
219
220	VTK_WRAP_PYTHON:BOOL=ON
221	VTK_USE_MANGLED_MESA:BOOL=OFF
222
223	VTK_USE_OFFSCREEN:BOOL=ON
224	#--------------------
225
226	cmake .
227	#It won't work but it will put some variables in that you need.
228
229	#Edit CMakeCache again and make the following changes
230
231	#----------------
232
233	VTK_USE_TK:BOOL=OFF
234
235	OSMESA_INCLUDE_DIR:PATH=..../stand/packages/mesa/include
236
237	OSMESA_LIBRARY:FILEPATH=..../stand/packages/mesa/lib/libOSMesa.so
238
239	PYTHON_INCLUDE_PATH:PATH=..../stand/packages/python/include/python2.6
240
241	PYTHON_LIBRARY:FILEPATH=..../stand/packages/python/lib/libpython2.6.so
242
243	OPENGL_INCLUDE_DIR:PATH=..../stand/packages/mesa/include
244
245	OPENGL_gl_LIBRARY:FILEPATH=..../stand/packages/mesa/lib/libGL.so
246
247	#----------------
248
249	cmake .
250
251	chmod +w Utilities/vtktiff/tif_fax3sm.c
252
253	make
254	make install
255
256
257	cd ../../packages
258	ln -s vtk-5.2.1 vtk
259	cd ..
260	\end{shellCode}
261
262	Now copy the \esfinley source into an \filename{escript.d} directory in \filename{stand}.
263
264	\subsection{Compiling escript}\label{sec:compileescriptlinux}
265
266	Change to the directory containing your escript source (\filename{escript.d}), then:
267
268	\begin{shellCode}
269	cd scons
270	cp linux_options_example.py YourMachineName_options.py
271
272	#edit the options file and make the following changes:
273	#-----------------------------------------------------------------
274	declare a PKG_ROOT variable at the top of the file eg:
275	PKG_ROOT="/home/jfenwick/stand/packages"
276
277	python_path = PKG_ROOT+"python/include/python2.6"
278	python_lib_path = PKG_ROOT+"python/lib"
279	python_libs = "python2.6"
280
281	boost_path = PKG_ROOT+"boost/include/boost-1_37"
282	boost_lib_path = PKG_ROOT+"boost/lib"
283	boost_libs = ["boost_python-gcc43-mt"]
284	# You could simlink the boost python library to give a shorter
285	# name but it's not worth it
286
287	usevtk = "yes"
288	#-------------------------------------------------------------------
289
290	cd ..
291
292	#Modify bin/escript
293	#--------------------------------------------------
294	STANDALONE=1
295
296	#Check to make sure the paths in the if [ $STANDALONE == 1 ]
297	#block are correct
298
299	#-----------------------------------------------------------------
300
301	#start a new terminal
302	cd stand
303	export PATH=$(pwd)/packages/scons/bin:$PATH
304	cd escript.d
305	eval $(bin/escript -e)
306	scons
307	\end{shellCode}
308
309	If you wish to test your build, then you can do the following.
310	Note this may take a while if you have a slow processor and/or less than 1Gb of RAM.
311	\begin{shellCode}
312	scons all_tests
313	\end{shellCode}
314
315	\subsection{Cleaning up}
316	Once you are satisfied, the \filename{escript.d/build} and \filename{\$PKG_ROOT/build} directories can be removed.
317
318	If you \emph{really} want to save space and do not wish to be able to edit or recompile escript, you can remove the following:
319	\begin{itemize}
320	\item From the \filename{escript.d} directory:\begin{itemize}
321	\item Everything except: \filename{bin}, \filename{include}, \filename{lib}, \filename{esys},
322	\filename{README_LICENSE}.
323	\item Hidden files, which can be removed using
324	\begin{shellCode}
325	find . -name .?* \| xargs rm -rf
326	\end{shellCode}
327	in the \filename{escript.d} directory.
328	\end{itemize}
329	\item from the \filename{packages} directory:
330	\begin{itemize}
331	\item \filename{scons}, \filename{scons-1.2.0}, \filename{cmake-2.6.3} and \filename{cmake}
332	\end{itemize}
333	\item \filename{package\_src}\footnote{Do not remove this if you intend to redistribute.}.
334	\end{itemize}
335
336	Please note that removing all these files may make it more difficult for us to diagnose problems.
337
338
339
340
341	\section{Additional Functionality}\label{sec:linaddfunc}
342	To perform visualisations you will need some additional tools.
343	Since these do not need to be linked with any of the packages above, you can install versions available for your
344	system, or build them from source.
345	\begin{itemize}
346	\item \filename{ppmtompeg} and \filename{jpegtopnm} from the \filename{netpbm} suite. - To build from source
347	you would also need \filename{libjpeg} and its headers as well as \filename{libpng}\footnote{libpng requires zlib to build} and its headers.
348	\item A tool to visualise VTK files. For example Mayavi or Visit.
349	\end{itemize}