Editing Software Development Platforms (section)

== Installing Development Tools ==

===Python===

OS-X actually includes python.  However, it tends to be an slightly outdated version of python.  So, the best thing to do is to get the official python distribution from http://python.org/download/ .  There are a couple of versions there, you want to make sure that you get the one labelled something like. '''Python 2.7.1 Mac OS X 64-bit/32-bit x86-64/i386 Installer (for Mac OS X 10.6)'''  The advantage of this version is that it is 64-bit.

Make sure that this new version of python is on your path, so when you run python, you get this version and not the system default one.  

You should have lines like the following at the bottom of your .bash_profile .  The python installation normally does this, but you should check to make sure:

 # Setting PATH for Python 2.7
 # The orginal version is saved in .bash_profile.pysave
 PATH="/Library/Frameworks/Python.framework/Versions/2.7/bin:${PATH}"
 export PATH

===numpy===

numpy is also included as a standard part of OS-X.  However, if you install a new version of python, you need need to install a corresponding version of numpy .  You can get it from http://sourceforge.net/projects/numpy/files/NumPy/1.5.1/ .  Make sure that it is named something like numpy-1.5.1-py2.7-python.org-macosx10.5.dmg ; The version that works with macosx10.3 is 32 bit only.

===scipy===

scipy is currently required for the faim functional tests.   You can get it from http://sourceforge.net/projects/scipy/files/ .  You need at least version 0.9 (earlier versions are 32 only).  Make sure you get a version compiled for python 2.7 .

=== XCode ===

XCode includes the gcc compiler, which you will need if you want to compile and C or C++ code.  If however you want to compile fortran code, you will need a different version of gcc.  See [[#gcc including gfortran]] .

You can get XCode from the Apple App store.  It's free.

===boost===

Boost is a high-quality collection of C++ libraries (additions to the C++ standard typically go through Boost).

Download the boost source code from http://www.boost.org .  Unpack it with a command like:

 tar xvjf boost_1_50_0.tar.bz2
 cd boost_1_50_0

First you need to build bjam, which is boost's native build tool. 

 ./bootstrap.sh

These is the command.  Note that it does not get installed - it is most convenient to just use it from the build directory (at least for static libraries).

 ./bjam link=static -j 4 stage

Here is the [[#Scripts_to_Set_Environment_Variables|setenv.sh]] script to put into the directory after installing.

----
<source lang=bash>
#!/bin/bash
 
SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"

export BOOST_ROOT="${SCRIPT_DIR}"
</source>
----

===cmake===

Grab the binary installer from the website: http://www.cmake.org/cmake/resources/software.html

Note that when upgrading CMake there are links in /usr/bin need to be manually deleted before the new version of CMake is installed:

:/usr/bin/ccmake -> /Applications/CMake 2.8-11.app/Contents/bin/ccmake
:/usr/bin/cmake -> /Applications/CMake 2.8-11.app/Contents/bin/cmake
:/usr/bin/cmake-gui -> /Applications/CMake 2.8-11.app/Contents/bin/cmake-gui
:/usr/bin/cmakexbuild -> /Applications/CMake 2.8-11.app/Contents/bin/cmakexbuild
:/usr/bin/cpack -> /Applications/CMake 2.8-11.app/Contents/bin/cpack
:/usr/bin/ctest -> /Applications/CMake 2.8-11.app/Contents/bin/ctest

:$ sudo rm -rf /usr/bin/ctest /usr/bin/cpack /usr/bin/ccmake /usr/bin/cmake /usr/bin/cmake-gui /usr/bin/cmakexbuild

=== swig ===

Get it from http://www.swig.org/download.html .

 tar xvzf swig-2.0.7.tar.gz
 cd swig-2.0.7

Now you'll need the pcre source code, which you can get from http://www.pcre.org/ .  Put it in the swig source code directory, then run

 Tools/pcre-build.sh

Now continue with building swig:

 ./configure --prefix=/opt/swig-2.0.7
 make
 sudo make install

===gdcm===

You can get gdcm from http://sourceforge.net/apps/mediawiki/gdcm/index.php?title=Downloads .

 tar xvzf gdcm-2.2.0.tar.gz
 mkdir gdcm-2.2.0-build
 cd gdcm-2.2.0-build
 source /opt/vtk-5.10.0/setenv.sh
 ccmake ../gdcm-2.2.0

CMake variables of note are:

{| border="1" cellpadding="2" cellspacing="0"
|-
! option
! Setting
|- valign="top"
| CMAKE_BUILD_TYPE      ||          Release
|- valign="top"
| CMAKE_INSTALL_PREFIX || /opt/gdcm-1.3.2
|- valign="top"
| GDCM_BUILD_SHARED_LIBS || ON
|- valign="top"
| GDCM_USE_VTK ||  ON 
|- valign="top"
| GDCM_WRAP_PYTHON || ON
|- valign="top"
| PYTHON_DIR  || /lib/python2.7
|- valign="top"
| SWIG_EXECUTABLE || /opt/swig-2.0.7/bin/swig
|}

Also if you installed a newer version of python than the system default (which you should have), then you'll need to make sure that CMake is finding that, and not the system default python.  Check the following CMake variables.

{| border="1" cellpadding="2" cellspacing="0"
|-
! option
! Setting
|- valign="top"
| PYTHON_INCLUDE_DIR || /Library/Frameworks/Python.framework/Versions/2.7/Headers
|- valign="top"
| PYTHON_LIBRARY || /Library/Frameworks/Python.framework/Versions/2.7/lib/libpython2.7.dylib
|}

 make

I got an error "i686-apple-darwin11-llvm-g++-4.2: -compatibility_version only allowed with -dynamiclib".  To fix this, run "make VERBOSE=1", then repeat the last command (including the preceeding cd command), replacing -bundle with -dynamiclib.  Once you do that, you have to also create the links (after dc'ing back to the root build directory):

 cd bin
 ln -s libvtkgdcmPython.2.2.0.so libvtkgdcmPython.2.2.so
 ln -s libvtkgdcmPython.2.2.so libvtkgdcmPython.so
 cd ..

 sudo make install

After installation there will be a file /opt/gdcm-2.2.0/lib/vtkgdcm.py .  This has a lot of pointless (for our installation) stuff in it, and generates an irrelevant error message.  So just replace the entire contents of that file with this:

 from libvtkgdcmPython import *

Here is the setenv.sh script:

<source lang=bash>
#!/bin/bash

source /opt/vtk-5.10.0/setenv.sh

SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"

export GDCM_ROOT="${SCRIPT_DIR}"
export GDCM_DIR="${SCRIPT_DIR}"
remove_path PATH '/.+/gdcm(-[^/]+)?/bin/?$'
add_path PATH "${GDCM_ROOT}/bin"
remove_path DYLD_LIBRARY_PATH '/.+/gdcm(-[^/]+)?/lib/?'
add_path DYLD_LIBRARY_PATH "${GDCM_ROOT}/lib"
remove_path PYTHONPATH '/.+/gdcm(-[^/]+)?/lib/?'
add_path PYTHONPATH "${GDCM_ROOT}/lib"
</source>

===Qt===

Note that you do NOT need to install Qt separately to build ParaView.  If you use the ParaView Superbuild, it will download and configure and build Qt internally exactly as it needs it.

====Recommended: Using a binary installer====

You can get a binary installer from http://download.qt-project.org/archive/qt/ .  Make sure that you download the Cocoa version, because the Carbon version won't work with any 64 bit code.

If you ever need to remove Qt as installed with the binary installer, you can do it with 

 sudo /Developer/Tools/uninstall-qt.py

====from source====

Get the source from http://get.qt.nokia.com/qt/source/qt-everywhere-opensource-src-4.6.4.tar.gz .

 ./configure -cocoa -arch x86_64 -release -framework -prefix /opt/qt-4.6.4
 make -j 8
 sudo make install

===VTK===

Get the software from http://www.vtk.org/VTK/resources/software.html .

Unpack the source code (this can be in any convenient directory, usually somewhere in your home directory):
 
 tar xvzf vtk-5.10.0.tar.gz

This will make a directory called VTK, but I like to rename it with the version

 mv VTK vtk-5.10.0

VTK is built with cmake, so refer to [[#Quick_CMake_Tutorial]]   Here are the cmake options that I typically choose that are different than the defaults:

{| border="1" cellpadding="2" cellspacing="0"
|-
! option
! Setting
|- valign="top"
| BUILD_EXAMPLES || ON
|- valign="top"
| BUILD_SHARED_LIBS || ON
|- valign="top"
| CMAKE_BUILD_TYPE      ||          Release
|- valign="top"
| CMAKE_INSTALL_PREFIX || /opt/vtk-5.10.0
|- valign="top"
| VTK_USE_QT || OFF
|- valign="top"
| VTK_WRAP_PYTHON || ON
|}

Also if you installed a newer version of python than the system default (which you should have), then you'll need to make sure that CMake is finding that, and not the system default python.  Check the following CMake variables.

{| border="1" cellpadding="2" cellspacing="0"
|-
! option
! Setting
|- valign="top"
| PYTHON_EXECUTABLE        ||        /Library/Frameworks/Python.framework/Versions/2.7/bin/python2.7
|- valign="top"
| PYTHON_INCLUDE_DIR || /Library/Frameworks/Python.framework/Versions/2.7/Headers
|- valign="top"
| PYTHON_LIBRARY || /Library/Frameworks/Python.framework/Versions/2.7/lib/libpython2.7.dylib
|- valign="top"
| TK_INTERNAL_PATH || /System/Library/Frameworks/Tk.framework/PrivateHeaders
|}

You can use it from the build directory.  (In fact this is necessary if you want to build vtkn88.)  In this case, you can use this [[#Scripts_to_Set_Environment_Variables|setenv.sh]] :

----
<source lang=bash>
#!/bin/bash
 
source /usr/local/bin/setenv_functions.sh
 
# Conflicts with VTK from faim, so remove that.
 
export NUMERICS88_ROOT
unset NUMERICS88_ROOT
remove_path PATH '/.+/[Nn]umerics88(-[^/]+)?(/.+)?/bin/?$'
remove_path DYLD_LIBRARY_PATH '/.+/[Nn]umerics88(-[^/]+)?(/.+)?/lib/?$'
remove_path DYLD_LIBRARY_PATH '/.+/[Nn]umerics88(-[^/]+)?(/.+)?/bin/?$'
remove_path PYTHONPATH '/.+/[Nn]umerics88(-[^/]+)?(/.+)?/lib'
remove_path PYTHONPATH '/.+/[Nn]umerics88(-[^/]+)?(/.+)?/bin/?$'
remove_path PATH '/.+/[Ff][Aa][Ii][Mm](-[^/]+)?(/.+)?/bin/?$'
remove_path DYLD_LIBRARY_PATH '/.+/[Ff][Aa][Ii][Mm](-[^/]+)?(/.+)?/lib/?$'
remove_path DYLD_LIBRARY_PATH '/.+/[Ff][Aa][Ii][Mm](-[^/]+)?(/.+)?/bin/?$'
remove_path PYTHONPATH '/.+/[Ff][Aa][Ii][Mm](-[^/]+)?(/.+)?/lib'
remove_path PYTHONPATH '/.+/[Ff][Aa][Ii][Mm](-[^/]+)?(/.+)?/bin/?$'

remove_path PATH '/.+/vtk(-[^/]+)?/bin/?$'
remove_path PATH '/.+/vtk(-[^/]+)?/.+/bin/?$'
remove_path DYLD_LIBRARY_PATH '/.+/vtk(-[^/]+)?/lib/vtk(-[^/]+)?/?'
remove_path DYLD_LIBRARY_PATH '/.+/vtk(-[^/]+)?/.+/bin/?$'
remove_path PYTHONPATH '/.+/vtk(-[^/]+)?/lib/python([^/]+)?/site-packages'
remove_path PYTHONPATH '/.+/vtk(-[^/]+)?/.+/bin/?$'
 
SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
VTK_DIR="${SCRIPT_DIR}"
add_path PATH "${VTK_DIR}/bin"
add_path DYLD_LIBRARY_PATH "${VTK_DIR}/bin"
add_path PYTHONPATH "${VTK_DIR}/bin"
</source>
----

Alternatively, if you install it to /opt/vtk-5.10.0, here is the [[#Scripts_to_Set_Environment_Variables|setenv.sh]] script to put into /opt/vtk-5.10.0 after installing.

----
<source lang=bash>
#!/bin/bash

source /usr/local/bin/setenv_functions.sh

# Conflicts with VTK from faim, so remove that.
 
export NUMERICS88_ROOT
unset NUMERICS88_ROOT
remove_path PATH '/.+/[Nn]umerics88(-[^/]+)?(/.+)?/bin/?$'
remove_path DYLD_LIBRARY_PATH '/.+/[Nn]umerics88(-[^/]+)?(/.+)?/lib/?$'
remove_path DYLD_LIBRARY_PATH '/.+/[Nn]umerics88(-[^/]+)?(/.+)?/bin/?$'
remove_path PYTHONPATH '/.+/[Nn]umerics88(-[^/]+)?(/.+)?/lib'
remove_path PYTHONPATH '/.+/[Nn]umerics88(-[^/]+)?(/.+)?/bin/?$'
remove_path PATH '/.+/[Ff][Aa][Ii][Mm](-[^/]+)?(/.+)?/bin/?$'
remove_path DYLD_LIBRARY_PATH '/.+/[Ff][Aa][Ii][Mm](-[^/]+)?(/.+)?/lib/?$'
remove_path DYLD_LIBRARY_PATH '/.+/[Ff][Aa][Ii][Mm](-[^/]+)?(/.+)?/bin/?$'
remove_path PYTHONPATH '/.+/[Ff][Aa][Ii][Mm](-[^/]+)?(/.+)?/lib'
remove_path PYTHONPATH '/.+/[Ff][Aa][Ii][Mm](-[^/]+)?(/.+)?/bin/?$'

remove_path PATH '/.+/vtk(-[^/]+)?/bin/?$'
remove_path PATH '/.+/vtk(-[^/]+)?/.+/bin/?$'
remove_path DYLD_LIBRARY_PATH '/.+/vtk(-[^/]+)?/lib/vtk(-[^/]+)?/?'
remove_path DYLD_LIBRARY_PATH '/.+/vtk(-[^/]+)?/.+/bin/?$'
remove_path PYTHONPATH '/.+/vtk(-[^/]+)?/lib/python([^/]+)?/site-packages'
remove_path PYTHONPATH '/.+/vtk(-[^/]+)?/.+/bin/?$'

SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"

VTK_ROOT="${SCRIPT_DIR}"
add_path PATH "${VTK_ROOT}/bin"
add_path DYLD_LIBRARY_PATH "${VTK_ROOT}/lib/vtk-5.10"
add_path PYTHONPATH "${VTK_ROOT}/lib/python2.7/site-packages"
</source>
----

===ITK===

Get the software from http://itk.org/ITK/resources/software.html .

Unpack the source code (this can be in any convenient directory, usually somewhere in your home directory):
 
 tar xvzf InsightToolkit-3.20.1.tar.gz

ITK is built with cmake, so refer to [[#Quick_CMake_Tutorial]]   Here are the cmake options that I typically choose that are different than the defaults:

{| border="1" cellpadding="2" cellspacing="0"
|-
! option
! Setting
|- valign="top"
| BUILD_EXAMPLES || ON
|- valign="top"
| BUILD_SHARED_LIBS      ||         ON
|- valign="top"
| CMAKE_BUILD_TYPE   ||             Release
|- valign="top"
| CMAKE_INSTALL_PREFIX || /opt/itk-3.20.1
|}

ITK does not install the VTK to ITK filters, and there seems to be no cmake option to request this, although the necessary files are in the source code tree.  Fortunately, they are just header and template files, so you can just copy them into place afterwards.  Something like this:

 sudo cp Wrapping/WrapITK/ExternalProjects/ItkVtkGlue/src/*.h /opt/itk-3.20.1/include/InsightToolkit
 sudo cp Wrapping/WrapITK/ExternalProjects/ItkVtkGlue/src/*.txx  /opt/itk-3.20.1/include/InsightToolkit

Here is the [[#Scripts_to_Set_Environment_Variables|setenv.sh]] script.

----
<source lang=bash>
#!/bin/bash

source /usr/local/bin/setenv_functions.sh

SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"

export ITK_ROOT="${SCRIPT_DIR}"
export ITK_DIR="${ITK_ROOT}/lib/InsightToolkit"
remove_path PATH '/opt/itk(-[^/]+)?/bin/?'
add_path PATH "${ITK_ROOT}/bin"
remove_path DYLD_LIBRARY_PATH '/opt/itk(-[^/]+)?/lib'
add_path DYLD_LIBRARY_PATH "${ITK_DIR}"
</source>
----

===gcc including gfortran===

gcc is included in XCode, however gfortran is not included, so we have to obtain gcc another way.


====binary installer ====

Get from http://hpc.sourceforge.net .  This is now the recommended method.



====from source====

I really don't recommend installing gcc from source, since it is non-trivial to do so.  Install it with macports if at all possible.  However, if for some reason you are unable to build gcc with macports, these instructions may be useful.

We require the 4.3 or newer gcc series, since it supports some Fortran 2003 features that we need (for cross-language building).  Also, the auto-vectorization of 4.3 is superior to earlier versions.

Installing and building gcc from source is not trivial, but it can be done as follows.  I recommend having a dedicated source-code build directory in your home direectory:

 mkdir -p Documents/source
 cd Documents/source

* Install GMP

 wget ftp://ftp.gnu.org/gnu/gmp/gmp-4.2.4.tar.bz2
 tar xvjf gmp-4.2.4.tar.bz2
 cd gmp-4.2.4
 ./configure ABI=32
 make -j 8
 make check
 sudo make install
 cd ..

NOTE: The -j 8 flag tells make to launch up to 8 building threads when possible.  This is to maximize the use of the 8 cores on the MacPro.

*Install MPFR

 wget http://www.mpfr.org/mpfr-current/mpfr-2.3.2.tar.bz2
 tar xvjf mpfr-2.3.2.tar.bz2
 cd mpfr-2.3.2
 ./configure --with-gmp-build=../source/gmp-4.2.4
 make -j 8
 make check
 sudo make install
 cd ..

*Install gcc

 wget http://gcc-ca.internet.bs/releases/gcc-4.3.2/gcc-4.3.2.tar.bz2
 tar xvjf gcc-4.3.2.tar.bz2
 mkdir build-gcc-4.3.2
 cd build-gcc-4.3.2
 ../gcc-4.3.2/configure --prefix=/opt/gcc-4.3.2 --enable-languages=c,c++,fortran --with-mpfr=../mpfr-2.3.2 --build=i686-apple-darwin9 --host=i686-apple-darwin9 --target=i686-apple-darwin9
 make -j 8
 # Now go have coffee, maybe lunch :)
 sudo make install

====Note on using custom-built gcc====

Generally, to use a custom-built gcc, you just have to specify the complete path to the compiler, like this:

 /opt/gcc-4.3.2/bin/gcc myprogram.c

Most build-systems will respect the environment variables CC, CXX and FC, so to set the default compilers, this will generally work:

 export CC=/opt/gcc-4.3.2/bin/gcc
 export CXX=/opt/gcc-4.3.2/bin/g++
 export FC=/opt/gcc-4.3.2/bin/gfortran

In addition, similarly-named variables exist by default for make files, so you can generally also do this:

 make CC=/opt/gcc-4.3.2/bin/gcc CXX=/opt/gcc-4.3.2/bin/g++ FC=/opt/gcc-4.3.2/bin/gfortran
o specify the complete path to the compiler, like this:

 /opt/gcc-4.3.2/bin/gcc myprogram.c

Most build-systems will respect the environment variables CC, CXX and FC, so to set the default compilers, this will generally work:

 export CC=/opt/gcc-4.3.2/bin/gcc
 export CXX=/opt/gcc-4.3.2/bin/g++
 export FC=/opt/gcc-4.3.2/bin/gfortran

In addition, similarly-named variables exist by default for make files, so you can generally also do this:

 make CC=/opt/gcc-4.3.2/bin/gcc CXX=/opt/gcc-4.3.2/bin/g++ FC=/opt/gcc-4.3.2/bin/gfortran

===gtest===

gtest is google's testing framework.  Some unit tests are written with it.  Generally, it is not absolutely required, as you can typically build projects without testing support.  However, this is not recommended, as the tests verify proper operation.

You can get gtest from here: http://code.google.com/p/googletest/ .

Unpack it in the usual way

 unzip gtest-1.6.0.zip
 cd gtest-1.6.0

Build it it:

 ./configure
 make

We're not going to actually install it; that is not recommended.

Here is the [[#Scripts_to_Set_Environment_Variables|setenv.sh]] script to put into /Users/eric/source/gtest-1.6.0 after installing.

----
<source lang=bash>
#!/bin/bash
#
 
source /usr/local/bin/setenv_functions.sh
 
export GTEST_ROOT=/Users/eric/source/gtest-1.6.0
</source>
----

===LaTeX===

The easiest is to get http://www.tug.org/mactex/ .

Put /usr/texbin on your PATH.

===dblatex===

dblatex is a tool for generating PDF output using LaTeX from docbook sources.  It is necessary for producing PDF output from asciidoc .

dblatex requires LaTeX, so install that first.

Get the source code from http://dblatex.sourceforge.net/ .

 tar xvjf dblatex-0.3.2.tar.bz2
 cd dblatex-0.3.2
 sudo python2.7 ./setup.py install --prefix=/opt/dblatex-0.3.2

Note: I use python2.7 instead of python just to be sure to get the python I installed, instead of the system python.

To use dblatex, you will need to set some environment variables:

 export PATH=/opt/dblatex-0.3.2:"$PATH"
 export PYTHONPATH=/opt/dblatex-0.3.2/lib/python2.7/site-packages:$PYTHONPATH"

Alternatively, here is the [[#Scripts_to_Set_Environment_Variables|setenv.sh]] script.

----
<source lang=bash>
#!/bin/bash
 
source /usr/local/bin/setenv_functions.sh

remove_path PATH '/.*/dblatex(-[^/]+)?/bin/?'
remove_path PYTHONPATH '/.*/dblatex(-[^/]+)?/lib'
 
SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
 
export DBLATEX_DIR="${SCRIPT_DIR}"
add_path PATH "${DBLATEX_DIR}/bin"
add_path PYTHONPATH "${DBLATEX_DIR}/lib/python2.7/site-packages"
</source>
----

===source-highlight===

source-highlight is used by asciidoc.

Another dependency, if source highlighting is used (and we do use it), is source-highlight.  You can get the source code from ftp://ftp.gnu.org/gnu/src-highlite/ .

 tar xvzf source-highlight-3.1.7.tar.gz
 cd source-highlight-3.1.7
 ./configure --prefix=/opt/source-highlight-3.1.7 --with-boost=/opt/boost-1.50.0
 make
 sudo make install

Here is the [[#Scripts_to_Set_Environment_Variables|setenv.sh]] script.

----
<source lang=bash>
#!/bin/bash

source /usr/local/bin/setenv_functions.sh

remove_path PATH '/opt/source-highlight(-[^/]+)?/bin/?'
remove_path DYLD_LIBRARY_PATH '/opt/source-highlight(-[^/]+)?/lib/?'

SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"

export SOURCEHIGHLIGHT_DIR="${SCRIPT_DIR}"
add_path PATH "${SOURCEHIGHLIGHT_DIR}/bin"
add_path DYLD_LIBRARY_PATH "${SOURCEHIGHLIGHT_DIR}/lib"
</source>
----

===asciidoc===

asciidoc is used for the faim manual.

The source code can be obtained from

http://sourceforge.net/projects/asciidoc/

It can be installed with

 tar xvzf asciidoc-8.6.8.tar.gz
 cd asciidoc-8.6.8
 ./configure --prefix=/opt/asciidoc-8.6.8
 make
 sudo make install

You'll need some docbook style sheets.  Download Docbook XML 4.5 from http://www.docbook.org/xml/4.5/ and unpack it inside /usr/local/share/xml/docbook/4.5.
Download the latest Docbook XSL version from http://sourceforge.net/projects/docbook/files/docbook-xsl/ and unpack it. The name should be of the form docbook-xsl-1.nn.n.tar.bz2. Put the results in /usr/local/share/xsl/docbook, thus effectively removing the version number from the directory name (for simplicity).

Now you'll need to create the file /etc/xml/catalog and populate it like this:

<source lang=xml>
<?xml version="1.0"?>
<!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN" "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">

<!-- ===== BEGIN docbook-xml entries ===== -->

<!--  docbook-xml V4.x  --> 
  <delegatePublic 
     publicIdStartString="-//OASIS//DTD DocBook XML"
     catalog="/usr/local/share/xml/docbook/4.5/catalog.xml"/> 

  <delegateSystem 
     systemIdStartString="http://www.oasis-open.org/docbook/xml/4" 
     catalog="/usr/local/share/xml/docbook/4.5/catalog.xml"/> 

<!-- ===== END docbook-xml entries ===== --> 

<!-- ===== BEGIN docbook-xsl entries ===== --> 

  <delegateURI 
     uriStartString="http://docbook.sourceforge.net/release/xsl/"
     catalog="/usr/local/share/xsl/docbook/catalog.xml"/> 

  <delegateURI 
     uriStartString="http://docbook.sf.net/release/xsl/"
     catalog="/usr/local/share/xsl/docbook/catalog.xml"/> 

<!-- ===== END docbook-xsl entries ===== -->

</catalog>
</source>

Here is the [[#Scripts_to_Set_Environment_Variables|setenv.sh]] script.

----
<source lang=bash>
#!/bin/bash
 
source /Users/Shared/install/dblatex-0.3.2/setenv.sh
source /Users/Shared/install/source-highlight-3.1.7/setenv.sh
 
remove_path PATH '/.*/asciidoc(-[^/]+)?/bin/?'
 
SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
 
export ASCIIDOC_DIR="${SCRIPT_DIR}"
add_path PATH "${ASCIIDOC_DIR}/bin"
</source>
----

I like to make one change, which is to change the indexterm macro so that secondary and tertiary entries are not automatically also promoted to primary index terms.  To do this, edit the file etc/asciidoc/docbook45.conf , find the section on indexterm, and comment out the lines that do that.

===GLE Graphics===

GLE is required to build the figures in the FAIM manual.

Install the binary following the instructions at http://www.gle-graphics.org/tut/mac.html .  (All you need is the Binary Installation instructions - just ignore the additional instructions related to compiling from source.)

You will need to put /Applications/QGLE.app/Contents/bin on your PATH:

 export PATH=/Applications/QGLE.app/Contents/bin:"$PATH"

===FFTW===

Get it from http://www.fftw.org/download.html .

Build the double-precision version:

 ./configure --enable-float --enable-sse2 --prefix=/opt/fftw-3.3
 make
 sudo make install

Then build the single-precision version:

 ./configure --enable-float --enable-sse2 --prefix=/opt/fftw-3.3
 make
 sudo make install

This builds only static libraries, which is typically what I want.

===Graphviz===

Required by doxygen if you want charts.  Then,

 tar xvzf graphviz-2.28.0.tar.gz
 cd graphviz-2.28.0
 export CPPFLAGS=-I/System/Library/Frameworks/Tk.framework/Versions/8.5/Headers
 ./configure --prefix /opt/graphviz-2.28.0
 make -j 4
 
Here is the setenv.sh script:

<source lang=bash>
#!/bin/bash
 
source /usr/local/bin/setenv_functions.sh

SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"

remove_path PATH '/opt/graphviz(-[^/]+)?/bin/?'
remove_path DYLD_LIBRARY_PATH '/opt/graphviz(-[^/]+)?/lib/?'

export GRAPHVIZ_DIR="${SCRIPT_DIR}"
add_path PATH "${GRAPHVIZ_DIR}/bin"
add_path DYLD_LIBRARY_PATH "${GRAPHVIZ_DIR}/lib"
</source>

===gnuplot===

Required for graphs in doxygen.

 tar xvzf gnuplot-4.6.0.tar.gz
 cd gnuplot-4.6.0
 ./configure --prefix /opt/gnuplot-4.6.0
 make -j 4
 sudo make install

Here is the setenv.sh script:

<source lang=bash>
#!/bin/bash
 
source /usr/local/bin/setenv_functions.sh

SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"

remove_path PATH '/opt/gnuplot(-[^/]+)?/bin/?'

export GNUPLOT_DIR="${SCRIPT_DIR}"
add_path PATH "${GNUPLOT_DIR}/bin"
</source>

===Doxygen===

 source /opt/graphviz-2.28.0/setenv.sh
 source /opt/gnuplot-4.6.0/setenv.sh
 ./configure --prefix /opt/doxygen-1.8.2
 make -j 4
 sudo make install

Here is the setenv.sh script:

<source lang=bash>
#!/bin/bash
 
source /usr/local/bin/setenv_functions.sh

SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"

remove_path PATH '/opt/doxygen(-[^/]+)?/bin/?'

export DOXYGEN_DIR=${SCRIPT_DIR}"
add_path PATH "${DOXYGEN_DIR}/bin"
</source>

===HDF5 and netCDF===

Get HDF5 from http://www.hdfgroup.org/downloads/index.html .

I used the CMake build for HDF5, instead of the automake build.  Note that for version 1.8.9 you have to apply a patch (or edit by hand one file) as described here: http://www.hdfgroup.org/ftp/HDF5/current/src/ .

Here are some interesting cmake options:

{| border="1" cellpadding="2" cellspacing="0"
|-
! option
! Setting
|- valign="top"
| BUILD_SHARED_LIBS ||               ON                                           
|- valign="top"
| CMAKE_BUILD_TYPE || Release
|- valign="top"
| CMAKE_INSTALL_PREFIX ||            /opt/hdf5-1.8.9
|- valign="top"
| HDF5_BUILD_CPP_LIB || OFF
|- valign="top"
| HDF5_BUILD_FORTRAN || OFF
|- valign="top"
| HDF5_BUILD_HL_LIB || ON
|- valign="top"
| HDF5_BUILD_TOOLS || ON
|- valign="top"
| HDF5_ENABLE_Z_LIB_SUPPORT || ON
|}

Build in the usual way for CMake.

Note that the automake build has all the defaults as above anyway, so it is just

 ./configure --prefix=/Users/Shared/install/hdf5-1.8.9

Here's a setenv script for setting environment variables:

<source lang=bash>
#!/bin/bash

source /usr/local/bin/setenv_functions.sh

remove_path PATH '/.*/hdf5(-[^/]+)?/bin/?'
remove_path DYLD_LIBRARY_PATH '/.*/hdf5(-[^/]+)?/lib/?'

SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"

export HDF5_DIR="${SCRIPT_DIR}"
export HDF5_ROOT="${HDF5_DIR}"
add_path PATH "${HDF5_DIR}/bin"
add_path DYLD_LIBRARY_PATH "${HDF5_DIR}/lib"
</source>

Now for netCDF, which you can get from ftp://ftp.unidata.ucar.edu/pub/netcdf . The standard package builds only the C interface:

 tar xvzf netcdf-4.2.1.tar.g
 cd netcdf-4.2.1
 source /opt/hdf5-1.8.9/setenv.sh
 export CPPFLAGS="-I$HDF5_DIR/include"
 export LDFLAGS="-L$HDF5_DIR/lib"
 ./configure --prefix=/opt/netcdf-4.2.1 --disable-dap --disable-doxygen 
 make -j 4
 make check
 sudo make install

Here is a setenv.sh script:

<source lang=bash>
#!/bin/bash
 
source /opt/hdf5-1.8.9/setenv.sh

remove_path PATH '/.*/netcdf(-[^/]+)?/bin/?'
remove_path DYLD_LIBRARY_PATH '/.*/netcdf(-[^/]+)?/lib/?'
remove_path PYTHONPATH '/.*/netcdf(-[^/]+)?/lib/?'

SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
 
export NETCDF4_DIR="${SCRIPT_DIR}"
add_path PATH "${NETCDF4_DIR}/bin"
add_path DYLD_LIBRARY_PATH "${NETCDF4_DIR}/lib"
add_path PYTHONPATH "${NETCDF4_DIR}/lib/python2.7/site-packages"
</source>

Now for the fortran interface:

 tar xvzf netcdf-fortran-4.2.tar.gz
 cd netcdf-fortran-4.2
 source /opt/netcdf-4.2.1/setenv.sh
 export FC=/opt/local/bin/gfortran-mp-4.4
 export CPPFLAGS="-I$NETCDF4_DIR/include -I$HDF5_DIR/include -DgFortran"

Note that the  -DgFortran part is to ensure correct name mangling in Fortran.  See http://www.unidata.ucar.edu/support/help/MailArchives/netcdf/msg09206.html .  A future version may not require this.

 export LDFLAGS="-L$NETCDF4_DIR/lib -L$HDF5_DIR/lib"
 ./configure --prefix=/opt/netcdf-4.2.1
 make -j 4
 make check
 sudo make install

For the python module netcdf4-python from http://code.google.com/p/netcdf4-python/ , I needed to make a link gcc-4.2 as follows (OS-X 10.7 only):

 cd /usr/bin
 sudo ln -s gcc-4.2 llvm-gcc-4.2

Then some usual stuff:

 tar xvzf netCDF4-1.0fix1.tar.gz
 mv netCDF4-1.0 netCDF4-python-1.0    # Rename to something more informative
 cd netCDF4-python-1.0
 source /opt/netcdf-4.2.1/setenv.sh

Now it turns out that with HDF 1.8.9 and python netCDF 1.0 we need to fix up the setup.py script a bit:

<source lang=diff>
*** setup.py.old	2012-07-11 09:40:08.603064046 -0700
--- setup.py	2012-07-11 09:40:17.566869824 -0700
***************
*** 21,26 ****
--- 21,28 ----
      for line in f:
          if line.startswith('#define H5_VERSION'):
              hdf5_version = line.split()[2]
+         elif line.startswith('#define VERSION'):
+             hdf5_version = line.split()[2]
      return hdf5_version
  
  def check_ifnetcdf4(netcdf4_includedir):
</source>

The build continues:

 python setup.py build
 sudo bash
 source /opt/netcdf-4.2.1/setenv.sh
 python setup.py install --prefix=/opt/netcdf-4.2.1
 exit