Licence:	GPL3
Author:		Richard Neher, Fabio Zanini
Date:		2012/09/12

Description:
------------
Intallation instructions and troubleshooting for the FFPopSim library.

This file is made of three parts:

   1. Requirements
   2. Installation instructions
   3. Troubleshooting

-------------------------------------------------------------------
1. REQUIREMENTS
-------------------------------------------------------------------
Make is used to build the FFPopSim library. The pure C++ part
requires:

- a C++ compiler and linker
- the GNU Scientific Library (http://www.gnu.org/software/gsl/)
- BOOST (http://www.boost.org/)

The python wrapper comes in two flavours. First, binaries are provided, for
which the requirements are only:

- Python 2.7
- NumPy 1.6 and MatPlotLib (http://www.scipy.org)

Second, you can build the Python bindings yourself. This requires both the
C++ and Python programs, plus the following:

- Distutils (http://docs.python.org/library/distutils.html)

Note for Python-only users: the Enthought Python Distribution
(http://www.enthought.com/products/epd.php) includes all the packages to run
FFPopSim *from the binaries*. It also includes Distutils. You still need the
C++ required programs, however, to build the Python wrapper yourself.

Optional dependencies
-------------------------------------------------------------------
The C wrapper for Python, in case you want to regenerate it, requires:

- SWIG 1.3 or 2.0 (http://www.swig.org)

NOTE: support for SWIG 3 is not implemented yet.

The C++ documentation, in case you want to rebuild it, requires:

- Doxygen (http://www.doxygen.org/)

The Python documentation, in case you want to rebuild it, requires:

- Sphinx (http://sphinx.pocoo.org/)

-------------------------------------------------------------------
2. INSTALLATION INSTRUCTIONS
-------------------------------------------------------------------
For Python-only users, binaries are provided for Linux and Mac OSX 10.6+,
for both 32 bit and 64 bit architectures, in the 'build' folder. Copy them
into a folder included in your PYTHONPATH or call, as a superuser,

	make python-install

to install them. This involves no compiling/linking at all, just plain file
copying: the binaries are essentially copied into you Python third-party
packages folder (e.g. /usr/local/lib/python2.7/site-packages/).

For all users, to build FFPopSim, a call

	make

should take care of everything (both C++ and Python parts are being built).
Have a look in the pkg folder for the results.


Full instructions
-------------------------------------------------------------------
Open the Makefile and have a look at the first few lines. Set the
required variables in the Makefile according to your platform (C/C++
compiler, Python interpreter, etc.) and preferences (optimization
level, compiler flags).

The variable CXXFLAGS can be used to add the paths for include files
for GSL and BOOST.

If you are compiling the Python part of FFPopSim, open also setup.py
and modify the 'includes' and 'library_dirs' lists there if GSL or
BOOST are not found.

You can build the various pieces separately:

- To build only the C++ sources, call

	make src

- To build the C++ test programs, call

	make tests

- To build the Python bindings, call

	make python

- To install the Python extension system-wide, call

	make python-install

  *as superuser*

- To rebuild the C++ documentation, call

	make doc

- To rebuild the Python documentation, call

	make python-doc

- To build both the C++ and Python parts (no documentation), just call

	make

- Finally, to rebuild everything including documentation, call

	make all

The C++ library and the Python module files are stored in the pkg
folder. Copy them into your system folders (e.g., /usr/local/include,
/usr/local/lib and /usr/local/lib/python2.7/site-packages,
respectively) to make them available to all users.

Documentation and examples
-------------------------------------------------------------------
Documentation and examples are online at:

	http://webdav.tuebingen.mpg.de/ffpopsim/

C++ and Python examples are available in the tests and examples
folders. They are commented, so you should be able to understand
what is being done there by reading the code directly.

-------------------------------------------------------------------
3. TROUBLESHOOTING
-------------------------------------------------------------------
Q. I cannot compile the C++ library because BOOST is not found, but
   I am sure it's installed!

A. BOOST is probably installed in a folder where your compiler cannot
   find it. This is for instance the case if you are on a Mac and
   installed it via Macports. There are two solutions: you either
   tell your compiler where your headers are via the CXXFLAGS variable
   in the Makefile; or you symlink your header folder, e.g.:

   sudo ln -s /opt/local/include /usr/local/include

   The latter solution is discouraged and should be avoided if
   possible.



Q. I cannot compile the Python bindings. The compiler complains that
   a number of gsl-related or boost-related files are not found!

A. Try opening the setup.py file and extend the lists 'includes' and
   'library_dirs'. In particular, add the paths of the header files 
   for GSL and BOOST on your system to 'includes', and the shared
   library files for GSL to 'library_dirs'.



Q. The examples work, but when I try to import FFPopSim from another
   Python script I get in ImportError message!

A. In order for Python to find FFPopSim, both FFPopsim.py and
   _FFPopSim.so must be in your PYTHONPATH. A cheap way of achieving
   this on a case-by-case basis is to write at the beginning of the
   script:

   import sys
   sys.path.append('<FFPOPSIM>/pkg/python')

   where <FFPOPSIM> is the folder in which FFPopSim was compiled. A
   more elegant solution is to install the library system-wide, using
   
   make python-install

   Note that you will be asked root priviledges for this operation.



Q. I am trying to use the Mac OSX binaries on OSX 10.5 or earlier, and
   I get an error like:

	unknown required load command 0x80000022

   What shall I do?

A. The shipped binaries do not work on such an old OSX version, but you can
   try to build FFPopSim youself. Install the most recent EPD Python
   distribution for your Mac OSX and all other building requirements (GSL,
   BOOST) and follow the instructions. Indeed, this is expected to work out
   just fine.



Q. I am trying to use the binaries but get the following error:

	ImportError: numpy.core.multiarray failed to import

   What shall I do?

A. Your version of NumPy differs from the one used to compile the shipped
   binaries, which is 1.6. Probably, you have an older version. You can
   choose between three options: (1) update your system; (2) download and
   use the most recent EPD Python distribution; (3) try to build FFPopSim
   yourself, downloading the building requirements (GSL, BOOST, etc.) and
   follow the instructions.

