Editing Software Development Platforms (section)

=Development on OS-X=
==Lists of what you actually need to install==

===For writing Python scripts that use vtkski===

For this purpose, you need only the bonelab Libraries binaries, which you can get from mike.kin .  Everything thing else is already a standard part of OS-X.

Note: For now this is wishful thinking, as I haven't actually built binaries of the bonelab libraries that wrap up and install the VTK libraries as well.  Therefore, for the time being, you probably need everything from the next section so you can build vtkski yourself.

===For modifying vtkski and other bonelab libraries, as well as applications written in C++===

You'll need:
*[[#XCode|XCode]]
*[[#cmake|cmake]]
*[[#boost|boost]]
*[[#VTK|VTK]]

As well, you may need [[#ITK|ITK]] and/or [[#Qt|Qt]] , depending on which libraries/applications you want to build.

===For building ParaView extensions===

You'll need everything in the above section, plus [[#Paraview|Paraview]] .  Actually you won't need to get and build VTK separately - it is included in the ParaView source code tree.  That internal version of VTK must be used for building ParaView plugins and extensions, and any libraries that they may use.

===For modifying faim===

For modifying the source code of faim, you'll need [[#boost|boost]] , plus a fortran complier, usually [[#gcc including gfortan]] .

Unless you want to build faim without tests (not recommended), you will also need [[#gtest|gtest]] .

==A Discussion of Directories==

It's generally not a good idea to mess with the directories that "belong" to OS-X.  This includes /usr .  Installing stuff to /usr is generally a very bad idea, since you might clobber system files.

Instead, it is conventional to install unix-style software into /usr/local .  Thus for example, the binaries get installed into /usr/local/bin, the libraries into /usr/local/lib, and so on.  This is acceptable, but has some drawbacks.  The biggest one is that typically it is impossible to install multiple versions of the same sotware simultaneously.  Another is that it can be hard to uninstall particular software, since the files get spread around all the subdirectories of /usr/local .

An alternative to using /usr/local for everything is to install particular packages into their own dedicated directores.  Conventionally, these are subdirectories of /opt .  So for example, we could install VTK 5.6.1 into /opt/vtk-5.6.1 .  Then the binaries would end up in /opt/vtk-5.6.1/bin, and the libraries in /opt/vtk-5.6.1/lib, and so on.  Now we can have multiple versions, and uninstallation is easy - just delete the directory.  One drawback is that, unlike /usr/local/bin and /usr/local/lib, these won't be on your paths by default, so they can't be found.  Generally we need to do something like this:

 export PATH=/opt/vtk-5.6.1/bin:"$PATH"
 export DYLD_LIBRARY_PATH=/opt/vtk-5.6.1/lib:"$DYLD_LIBRARY_PATH"

These lines can go in .bash_profile for a permanent change, or, you can put them into another file, say setvars.sh, and just do this to run it and import the environment variables:

 source setvars.sh

One tip is that you can create links in opt to your favorite versions, like this:

 cd /opt
 ln -s vtk-5.6.1 vtk

Then you don't have to change your .bash_profile or setvars.sh file when you want to switch to a different version.  You simply change the symbolic links in /opt .  The export lines become simply

 export PATH=/opt/vtk/bin:"$PATH"
 export DYLD_LIBRARY_PATH=/opt/vtk/lib:"$DYLD_LIBRARY_PATH"

I will generally assume that this has been done.

There is one additional "standard" directory, and that is /opt/local .  It belongs to macports, so it's best not to mess with it.

==Scripts to Set Environment Variables==

If you want to use different versions of installed software, or not have everything on your path all the time, it is convenient to use scripts to modify the environment variables.  For convenience, here is a script that provides some useful functions for modifying paths.  I name it setenv_functions.sh and put it in /usr/local/bin.
----
<source lang=bash>
#!/bin/bash
#
# setenv_functions.sh
#
# Eric Nodwell, January 2011
#
# Provides functions useful for modifying system paths.
#
# You call this from other bach scripts like this:
#
#    source /usr/local/bin/setenv_functions.sh
#
# Then you can make use of the functions defined below.
#  
# Example usage: add_path PATH /usr/my/path
#
function add_path
{
  echo -e "Adding to ${1}: \033[1;34m${2}\033[0m"
  eval "OLDLIST=\"\$$1\""
  if [ -n "${OLDLIST}" ] ; then
    eval "$1=\"$2:\$$1\""
  else
    eval "$1=\"$2\""
  fi
  eval "export $1"
}
 
# Example usage: remove_path PATH /usr/my/path
#
# The second argument can be a regular expression for pattern matching.
#
function remove_path
{
  eval "OLDLIST=\"\$$1\""
  REMOVALLIST=$( echo ${OLDLIST} | tr -s ":" "\n" | grep -wE "${2}" | tr -s "\n" ":" | sed "s/:$//" )
  if [ -n "${REMOVALLIST}" ] ; then
    echo -e "Removing from ${1}: \033[1;31m${REMOVALLIST}\033[0m"
    NEWLIST=$( echo ${OLDLIST} | tr -s ":" "\n" | grep -vwE "${2}" | tr -s "\n" ":" | sed "s/:$//" )
    eval "$1=\"$NEWLIST\""
    eval "export $1"
  fi
}
 
# Example usage: check_path PATH /usr/my/path
#
# The second argument can be a regular expression for pattern matching.
#
function check_path
{
  eval "OLDLIST=\"\$$1\""
  CHECKLIST=$( echo ${OLDLIST} | tr -s ":" "\n" | grep -wE "${2}" | tr -s "\n" ":" | sed "s/:$//" )
  test -n "${CHECKLIST}"
  return $?
}
# Example usage: add_path PATH /usr/my/path
#
function add_path
{
  echo -e "Adding to ${1}: \033[1;34m${2}\033[0m"
  eval "OLDLIST=\"\$$1\""
  if [ -n "${OLDLIST}" ] ; then
    eval "$1=\"$2:\$$1\""
  else
    eval "$1=\"$2\""
  fi
  eval "export $1"
}

# Example usage: remove_path PATH /usr/my/path
#
# The second argument can be a regular expression for pattern matching.
#
function remove_path
{
  eval "OLDLIST=\"\$$1\""
  REMOVALLIST=$( echo ${OLDLIST} | tr -s ":" "\n" | grep -wE "${2}" | tr -s "\n" ":" | sed "s/:$//" )
  if [ -n "${REMOVALLIST}" ] ; then
    echo -e "Removing from ${1}: \033[1;31m${REMOVALLIST}\033[0m"
    NEWLIST=$( echo ${OLDLIST} | tr -s ":" "\n" | grep -vwE "${2}" | tr -s "\n" ":" | sed "s/:$//" )
    eval "$1=\"$NEWLIST\""
    eval "export $1"
  fi
}

# Example usage: check_path PATH /usr/my/path
#
# The second argument can be a regular expression for pattern matching.
#
function check_path
{
  eval "OLDLIST=\"\$$1\""
  CHECKLIST=$( echo ${OLDLIST} | tr -s ":" "\n" | grep -wE "${2}" | tr -s "\n" ":" | sed "s/:$//" )
  test -n "${CHECKLIST}"
  return $?
}
</source>
----

There will be several examples below making use of this script.  See for example [[#asciidoc|asciidoc]] , where a script /opt/asciidoc-8.6.3/setenv.sh is created .  You use it like this:

 source /opt/asciidoc-8.6.3/setenv.sh

The output will look something like:

 Adding to DYLD_LIBRARY_PATH: /opt/boost-1.45.0/lib
 Adding to PATH: /opt/source-highlight-3.1.4/bin
 Adding to DYLD_LIBRARY_PATH: /opt/source-highlight-3.1.4/lib
 Adding to PATH: /opt/dblatex-0.3/bin
 Adding to PYTHONPATH: /opt/dblatex-0.3/lib/python2.7/site-packages
 Adding to PATH: /opt/asciidoc-8.6.3/bin

==Quick CMake Tutorial==

A lot of software that we use uses cmake as a build system.  Rather than repeat generic instructions over and over, I will present generic usage here.

===Creating a build directory===

CMake can build the software into any directory.  Usually the most sensible thing to do is to create a build directory in the source tree and run cmake from there.

 cd some_project_source
 mkdir build
 cd build

Now you need to generate a configuration to build.  There are two standard options: a command line interface and a graphical client.

===Configuration with ccmake===

Start it with

 ccmake ..

Hit C for configure.  A table of variables will appear alter them as described for the particular project.  Some variables are marked as Advanced and will only be visible after you hit T for toggle advanced.  Keep hitting C, and modifying variables as required, until the Generate options appears.  Then hit G for generate and ccmake will exit.

===Configuration with the CMake Graphical Client===

Start it by double-clicking on the icon, or with the command

 cmake-gui

Need to finish this...

===Building===

Once you've generated the configuration, you can just build the project like this:

 make

If it's a big project, you may want add -j 8 to that.  That will use 8 parallel threads for compilation.

To install the software, you now run

 sudo make install

==MacPorts==

Macports is a package management tool for OS-X.  It will automatically resolve dependencies, down source code, apply patches, and compile.

This sounds wonderful, however it has some drawbacks.  For one, you don't have any choice in version of the software installed, and sometimes the available ports are somewhat outdated.  Also, it tends to pull in more dependencies than are strictly required, and to duplicate unnecessarily many OS-X system files.

I therefore tend to use macports only for very simple software, or for software that would otherwise be quite difficult to install.

I recommend not installing macports at all if you can avoid it without too much trouble.

===Installation===

See http://www.macports.org/ .

===Configuring Macports===

I like to add this line to /opt/local/etc/macports/variants.conf:

 +no_x11 +quartz

This way, x11 functionality won't be built where possible.  These can lead to a huge reduction in the number of required dependencies.

macports by default uses single-process building.  Since many ports take a long time to compile, it is useful to speed things up by enabling multi-process building.  Do to this, edit /opt/local/etc/macports/macports.conf and set <tt>buildmakejobs</tt> to 0.  This will cause it to use a number of build jobs equal to the number of processors in the system.

== 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

==Tips==

===A trash command for OS-X===

OS-X doesn't seem to have a standard easy way to delete things from the command line such that they get moved to the trash (<tt>rm</tt> removes things permanently).  This little script will do the trick: [[Media:trash.sh]].  Rename this file simply <tt>trash</tt> and put it somewhere on your path (such as <tt>/usr/local/bin</tt> or <tt>~/bin</tt>).

You use it just like this:

 trash some_file some_other_file folders_too

It will expand wildcards, so stuff like this works:

 trash ~/Documents/blue*

For wildcards, the option <tt>-v</tt> is useful to see what actually does get trashed.

===Working with Objects and Libaries===

See the corresponding section [[Development for Linux#Working with Objects and Libaries]]

otool -L is useful for finding out what dynamic libraries are required.

install_name_tool is useful for changing the name or rpath of libraries.  Refer to the man page.

==Trouble Shooting==

===dyld: Symbol not found: __cg_jpeg_resync_to_restart===

If you get this error message from cmake, it is due to a conflict between macport's jpeg library and the OS-X jpeg library.  You can generally fix by deactivating jpeg in macports, forcing the use of the system jpeg:

 sudo port deactivate jpeg tiff libpng


[[Image:Redirect.jpg|15px]] [[#top|''Return to Contents'']] or [[Main_Page|''Return to Main Page'']]