Building and installing Gamera

Last modified: June 06, 2018

Contents

Linux (and other *nix)

Prerequisites

  • Python 2.3 and later are supported, though Python 2.4 or later is recommended.

    You will need to have the headers (but not the complete source) to build Gamera from source code. Most Linux distributions include these as a separate package (eg. python-dev or python-devel).

  • wxPython 2.4.x or later (wxPython 2.8.x or later up to 3.0.x recommended for full functionality).

  • gcc version 3.1 or later.

  • libtiff 3.5.x or later

  • libpng 1.2.x or later

If any of these prerequisites is installed in a non standard directory, you can use the environment variables CFLAGS and LDFLAGS to pass its locations to the build script, e.g.:

CFLAGS=-I/usr/local/include
LDFLAGS=-L/usr/local/lib
export CFLAGS LDFLAGS

Standard Build and Install

Gamera is built using the Python-standard Distutils system. Open a terminal and type:

python setup.py build
sudo python setup.py install

By default, parallelization of the genetic algorithms is only compiled into Gamera under Linux and with gcc version > 4.2, because we could only get it running in this environment. If you are sure that you have unbroken OpenMP support on your system, you can compile Gamera with:

python setup.py build --openmp=yes

If Gamera is compiled with OpenMP on your system, but OpenMP does not work on your system for some reason, you can switch it off with:

python setup.py build --openmp=no

Installing without root privileges

If you do not have root access to your machine, you can make a local installation of Gamera.

A quick-and-easy way to do this is to use the virtual_python.py script available here, and then follow the standard installation instructions (without using sudo):

python setup.py build
python setup.py install

Alternatively, you can set up a local installation by hand.

Make a local python module directory somewhere that you have write privileges (such as your home directory):

mkdir ~/python

From the Gamera build directory, install Gamera into that directory:

python setup.py install --home=~/python

Set up an environment variables so Python can find stuff there (you may want to add this to your ~/.bash_profile file):

export PYTHONPATH=~/python/lib/python

Add the local Python scripts directory to your path:

export PATH=~/python/bin:$PATH

Now you should be able to run the gamera_gui script from the command line.

Running

Run the gamera_gui script, which should have installed to /usr/local/bin. This file can also be copied anywhere (such as the Desktop) and double-clicked to run Gamera.

Note

Running the script from the root of the source tree will not work, since it will not be able to find the compiled version of Gamera.

Installing without wxPython

When you need Gamera as a backend for document processing routines on a server and do not need the GUI, it can save a lot of trouble to avoid the installation of wxPython. For this case, use the option --nowx for setup.py:

python setup.py --nowx build
sudo python setup.py --nowx install

Mac OS-X

On OS-X 10.5 (Panther) up to 10.10 (Yosemite), Gamera compiled oout of the box with the Apple command line develloper tools and the python and wxpython that came preinstalled with the OS. Since version 10.11 (El Capatain), the "system integrity protection" (SIP) prevents installation of third party packages system wide on OS-X. You must therefore use virtualenv on newer OS-X to create a virtual environments.

Moreover, Gamera currently requires wxPython before 4.0. Versions up to 3.0.x came installed with OS-X, but are not shipped with OS-X >= 10.11. On OS-X 10.11 (El Captain) and above, wxPython must therefore be compiled from the sources.

Installation up to 10.10 (Yosemite)

Prerequisites

Gamera installs out of the box on 10.5 (Leopard) up to 10.10 (Yosemite). The only prerequisite is to install the comamnd line tools of XCode, which are avalibale for free from the Apple App Store.

Build and Install

Gamera is built using the Python-standard Distutils system. To build Gamera, open a terminal and type:

# the following line is only required on OS-X 10.6 and later
export CFLAGS="-stdlib=libstdc++ -mmacosx-version-min=10.6"
python setup.py build

and then to install (you'll need to have admin privileges):

sudo python setup.py install

The script gamera_gui is installed to /usr/local/bin, which is also in the default search PATH for programs.

Running

Start the Terminal application and run the gamera_gui script.

Note

Running the script from the root of the source tree will not work, since it will not be able to find the compiled version of Gamera.

Installation on 10.11 (El Captain) and above

Prerequisites

Due to the OS-X builtin "system integrity protection" (SIP), wxPython cannot be installed into the python branch shipped with OS-X. Moreover, you must install wxPython from the sources, because binary packages are only available for wxPython 4.x, and Gamera requires an older version of wxPython.

To avoid possible problems with SIP and the python shipped with OS-X, you can install python from homebrew and also install virtualenv with:

brew install python2
pip2 install virtualenv

For the combination Python 2.7 with wxPython 3.0, you must first setup a virtual environment and activate it, e.g. with:

virtualenv /usr/local/lib/py2wx3
source /usr/local/lib/py2wx3/bin/activate

Download the source code of wxPython 3.0.2 from the "Old releases" section on wxpython.org and unpack it. There is one fix necessary: in src/osx/webview_webkit.mm, add a cast to WebBackForwardList in lines 936 and 954 as in the following example:

WebBackForwardList* history = (WebBackForwardList*)[m_webView backForwardList];

Then you can compile and install wxPython with the following commands:

cd root_to_wx_sources/wxPython
CPPFLAGS=-D__ASSERT_MACROS_DEFINE_VERSIONS_WITHOUT_UNDERSCORES=1
export CPPFLAGS
python build-wxpython.py --build_dir=../bld --osx_cocoa --install

This will install wxPython into the virtual environment.

Build and install

You can install Gamera into the same virtual environment with:

source /usr/local/lib/py2wx3/bin/activate
cd root_to_gamera_sources
python setup.py build
python setup.py install

Running

On OS-X, wxPython applications do not run in virtualenvs, because wxPython requires a "Framework build of python". Fortunately, there is a simple workaround: store the following shell script as gamera_gui in $HOME/bin and modify the PATH variable in $HOME/.profile such, that $HOME/bin is quite at the beginning of the list. Then you can run gamera_gui from the shell, and the script handles the setup of the virtualenv automatically. (Thanks to George V. Reilly for proposing this fix).

#
# wrapper script for running gamera_gui
# from virtualenv with homebrew python
#

source /usr/local/lib/py2wx3/bin/activate

WXPYTHON_APP="gamera_gui"
PYVER="$(python --version 2>&1 | cut -d ' ' -f 2 | cut -d '.' -f 1,2)"

if [ -z "$VIRTUAL_ENV" ] ; then
    echo "You must activate your virtualenv: set '$VIRTUAL_ENV'"
    exit 1
fi

SYSTEM_FRAMEWORK_PYTHON_ROOT="/Library/Frameworks/Python.framework/Versions/$PYVER"
# OS X >= 10.10
SYSTEM_FRAMEWORK_PYTHON_ROOT="/System$SYSTEM_FRAMEWORK_PYTHON_ROOT"

PYSUBVER="$(python --version 2>&1 | cut -d ' ' -f2)"  # e.g., 2.7.10
BREW_PYTHON_ROOT="`ls -d $(brew --prefix)/Cellar/python@2/$PYSUBVER*`"
BREW_PYTHON_ROOT="$BREW_PYTHON_ROOT/Frameworks/Python.framework/Versions/$PYVER"

PYTHON_BINARY="bin/python$PYVER"
FRAMEWORK_PYTHON="$BREW_PYTHON_ROOT/$PYTHON_BINARY"

VENV_SITE_PACKAGES="$VIRTUAL_ENV/lib/python$PYVER/site-packages"

# Ensure wx.pth is set up in the virtualenv
test -e "$VENV_SITE_PACKAGES/wx.pth" || \
  cp "/Library/Python/$PYVER/site-packages/wxredirect.pth" "$VENV_SITE_PACKAGES/wx.pth"

# Use the Framework Python to run the app
export PYTHONHOME=$VIRTUAL_ENV
exec "$FRAMEWORK_PYTHON" "$VIRTUAL_ENV/bin/$WXPYTHON_APP" $*

Microsoft Windows

Using the binary installer

The binary installers only work with one specific Python version so you must first make sure that your Python installation matches this version. The required version is indicated by the filename of the binary installer, e.g. gamera-3.4.1.win-amd64-py2.7.exe for the 64bit version of Python 2.7.

Note that the installer might show an error message in the last screen, which can be ignored. The installer should create a script file Gamera.py on the desktop of the installing user, which can be used to start the Gamera GUI with a double click.

Installing from source

Currently, Gamera can be built using the MingW32/GNU toolset or with the Microsoft SDK. The Python core distribution for Windows officially only supports the latter option, though it is possible to use MingW, albeit only the 32bit version of MingW (gcc). The state is currently not very satisfactory, because MingW is not officially supported by Python and the Microsoft SDK is not officially supported by Gamera (volunteers are welcome!).

There are thus three options to compile Gamera on Windows:

If you have success with other compilers and configurations, please consider contributing your experiences to this documentation.

Prerequisites

  • Python 2.5.x or later (only the distribution from python.org has been tested)
  • wxPython 2.6.x or later (wxPython 2.8.x or later recommended for full functionality)

Microsoft SDK

For building extensions for Python 2.6, 2.7, 3.0, 3.1 and 3.2 (both 32 and 64 bit), Microsoft Visual C++ 2008 (Microsoft Visual Studio 9.0) is the compiler that is suitable. You will need the Microsoft Windows SDK for Windows 7 and .NET Framework 3.5 SP1.

Note that this lacks some files required by the C99 standard, so you must additionally download the header files stdint.h and inttypes.h from the msinttypes project and copy them to the include directory of the SDK installation.

Assuming that you have installed the 64bit version of Python, you can compile Gamera with the following commands from the Microsoft SDK shell prompt (the color command is not necessary, but setenv can change the colors of the terminal to an unreadable combination):

setenv /x64 /release
color 0e
set DISTUTILS_USE_SDK=1
cd \path\to\gamera-sources
\path\to\python.exe setup.py bdist_wininst

The installer will be built in the subdirectory dist and can be started by double click in the explorer. Note that the installer might display an error message at the end, depending on the Python distutils version shipped with your Python installation. This message can simply be ignored.

Standalone Mingw32

Install the Mingw32 port of gcc from http://mingw.org/. Make sure that you do not only install gcc-core, but also g++ and make. Add the bin subdirectory of your Mingw32 installation to the environment variable PATH.

Assuming you have installed Python to C:\Python275, you can then compile gamera at a DOS command prompt from the root directory of the gamera source code with:

C:\Python27\python setup.py build --compiler=mingw32 bdist_wininst

This will create a Windows installer, including uninstallation support, in the dist subdirectory. It can be started with a double click in the Explorer, or from the DOS command prompt with:

start dist\gamera-*.exe

Note

Fixes for common problems:

  • The Python 2.6 binary from python.org requires libmsvcr90.a, which is an erroneous in some versions of Mingw32. To fix it, you can recreate the file from the DLL msvcr90.dll that comes with Python 2.6 with pexports and dlltool (the latter is part of Mingw32):

    pexports msvcr90.dll > msvcr90.def
    dlltool --input-def msvcr90.def --dllname msvcr90.dll --output-lib libmsvcr90.a -k
    

    With Python 2.7 and Mingw gcc 4.6, these changes are not necessary.

  • Recent versions of the Mingw gcc no longer support the -mno-cygwin option, which is however passed on by the Python distutils. If you run into this error, you can simply remove the option from the file:

    C:\Python27\lib\distutils\cygwinccompiler.py
    

Mingw32 inside Cygwin

Use the installer from http://www.cygwin.com/ to install Cygwin, including the g++-mingw32 compiler and the MingW32 libraries. If you plan to track development of Gamera, you will probably also want to install subversion.

The important thing to note here is that we are using Cygwin's Mingw32 compiler to build for the standard (non-Cygwin) Python from python.org. After a clean install of Cygwin, typing 'python' will start up Cygwin's version of Python, not the one from python.org. Therefore, you will want to add the standard Python to your Cygwin PATH using the command (assuming you installed Python in standard location):

export PATH=/cygdrive/c/Python25/:$PATH

Ensure you are using the correct Python by typing:

which python

The result should be /cygdrive/c/Python25/python.exe, not /usr/bin/python.

Beware that the file /usr/bin/gcc installed by Cygwin actually is not the compiler executable, but a symbolic link. Symbolic links are not supported by MS Windows, but are a Cygwin-only feature. This means that the Python Distutils system cannot execute /usr/bin/gcc and the build command will fail. To fix this, replace the symbolic link with the actual compiler executable:

cp /usr/bin/gcc-3 /usr/bin/gcc
cp /usr/bin/g++-3 /usr/bin/g++

From here on, you can proceed as for the standalone Mingw32 toolchain, i.e.:

python setup.py build --compiler=mingw32 bdist_wininst
dist/gamera-*.exe