Building from source
From Phycas
Contents |
Assumptions
Operating System
These instructions have been verified on machines running Ubuntu (version 10.04) and MacOS (version 10.6.4). They are not intended for use with Windows systems (a binary release is available for that).
Development environment
Note that precompiled binaries for Mac OS X are available, so you should only use these instructions if for some reason that doesn't suit. To compile Phycas on a MacOS 10.x system, you will need to have XCode from Apple's Developer Tools already installed. If you do not already have XCode on your system, you can download it at http://developer.apple.com/tools/download/. This is a free download, but you will first have to register with Apple Developer Connection; instructions are provided on the download page.
Shell
This document assumes that you are using the bash shell. For an introduction to working with a UNIX shell see http://www.ee.surrey.ac.uk/Teaching/Unix/. On a Mac, the most common application used to create shell sessions is Applications/Utilities/Terminal.app.
Boost version
Phycas requires the Boost Python library, and this document assumes you are using boost_1_48_0. If you do not have Boost installed, there are instructions below for installing it.
| Note: These instructions will not work for versions of Boost earlier than 1.34.0 because of a major change in the Boost build system between versions 1.33.1 and 1.34.0 |
Nexus Class Library version
Phycas requires the Nexus Class Library (NCL), and this document assumes you are using version 2.1.17. If you do not have NCL installed, there are instructions below for installing it.
Python version
Phycas requires version 2.3 or later of Python. These instructions assume that you are using the latest version in the Python 2 series, version 2.7. Phycas is currently not designed to work with Python 3.x.
Obtaining and building prerequisites
If the above tools are not already installed on your system, you will need to download and install them according to the instructions below.
Obtaining Python
To determine your Python version, open a terminal window and type
python -V
(Note the capital V, python -v means something else!). If you do not have Python, or if you have an older version (i.e. < 2.3), you will need to obtain and install a recent version (preferably 2.7).
Python is freely available from http://www.python.org/
It is possible that you have a recent version of Python but not the development libraries and headers (you must have Python.h in order to build Phycas). In Red Hat Fedora systems, the easiest way to obtain the Python headers and libraries is using yum:
yum install python-devel.i386
Installing Boost
Download and Unpack Boost
Download the latest version of Boost from http://www.boost.org/. To do this directly from the command line on your Linux machine, use the Boost web site to copy the link to your clipboard, then use the curl command to do the downloading:
cd $HOME curl -L http://sourceforge.net/projects/boost/files/boost/1.48.0/boost_1_48_0.tar.gz/download > boost_1_48_0.tar.gz
The -L flag is important: it causes curl to follow links to the correct mirror site.
The rest of this document will assume you downloaded boost_1_48_0.tar.gz to your home directory and unpacked it as follows:
cd $HOME tar zxvf boost_1_48_0.tar.gz
Build the bjam executable
Now build the bjam executable, which will be used to compile both the Boost Python dynamic link library as well as the dynamic link libraries composing the phycas package.
cd $HOME/boost_1_48_0/tools/build/v2/engine ./build.sh
(In boost_1_45_0, the directory has been changed to boost_1_45_0/tools/build/v2/engine/src.) This creates a directory named bin.<platform-specifier> within which the bjam executable may be found. Note that <platform-specifier> is a placeholder; i.e. you will actually see a directory named bin.linuxx86 or bin.macosxx86, depending on your platform.
Installing NCL
Download and unpack NCL
Download the latest version of NCL from http://sourceforge.net/projects/ncl/. To do this directly from the command line on your Linux machine, use the NCL SourceForge web site to locate the download link and copy it to your clipboard, then use the curl command to do the actual downloading:
cd $HOME curl -L http://sourceforge.net/projects/ncl/files/latest/download > ncl-2.1.17.tar.gz
The -L flag is important: it causes curl to follow links to the correct mirror site.
The rest of this document will assume you downloaded ncl-2.1.17.tar.gz to your home directory and unpacked it as follows:
cd $HOME tar zxvf ncl-2.1.17.tar.gz
Compiling and installing NCL
You should now have a directory $HOME/ncl-2.1.17. Use the following commands to compile and install NCL (if you do not have superuser privileges, see alternative instructions below):
cd $HOME/ncl-2.1.17 ./configure make sudo make install
If you do not have superuser privileges, you can install NCL into your home directory as follows (be sure to replace /home/me with the path to your actual home directory):
cd $HOME/ncl-2.1.17 ./configure --prefix=$HOME make make install
After make install, the NCL libraries should be present in the directory /usr/local/lib/ncl.
Building Phycas
Download Phycas
Use the link on the download page to download the Phycas source distribution to a directory of your choice. This will be in the form of a gzipped tar file.
Build Phycas
Copy the build_template.sh script in the phycas directory to build.sh. If you installed Boost, NCL and Phycas according to the instructions above, you may not need to modify anything. If building on MacOS, you wil need to open build.sh in a text editor and change the variable OSTYPE to darwin and linuxx86 to macosxx86_64 (or whatever directory was created when you build bjam).
Here is a version of that file using the paths we've been assuming throughout this tutorial (and with comments removed):
#!/bin/sh
export OSTYPE="linux"
export BOOST_ROOT="$HOME/boost_1_48_0"
export PATH="${PATH}:$BOOST_ROOT/tools/build/v2/engine/bin.linuxx86"
export BOOST_BUILD_PATH="${BOOST_ROOT}/tools/build/v2"
export PHYCAS_ROOT="$HOME/Phycas-1.2.0"
export NCL_ALREADY_INSTALLED=1
export NCL_INSTALL_DIR="/usr/local"
bjam release
Make the build.sh file executable using the chmod command:
chmod +x build.sh
Run the build.sh script to build Phycas (you will need to precede the file name with ./ if your $PATH environmental variable does not include the current working directory):
./build.sh
Running Phycas
Tell Python how to find Phycas
You are now ready to run Phycas. A couple environmental variables need to be defined in order for Python to be able to locate the Phycas module and its associated libraries. The least intrusive approach is to create a shell script named, e.g., phycas.sh, that defines these variables, starts python in interactive mode and imports Phycas. Here is an example of such a script:
#!/bin/bash
export PYTHONPATH="$HOME/Phycas-1.2.0"
export LD_LIBRARY_PATH="$HOME/Phycas-1.2.0/phycas/Conversions:/usr/local/lib/ncl"
if [ $# -gt 0 ]
then
python -i $1
else
python -ic "from phycas import *"
fi
Note: on Macs, replace LD_LIBRARY_PATH with DYLD_LIBRARY_PATH.
Note: if you installed ncl in your home directory, replace /usr/local/lib/ncl with $HOME/lib/ncl in LD_LIBRARY_PATH.
The script above is designed to be used in either of two modes. If you run it without command line arguments, then Python will start in interactive mode (the -i switch) and run the command "from phycas import *" (the -c switch). This mode is useful when you want to examine the online help or experiment. For real analyses, you will probably create a Python script file. If you supply the name of this script on the command line, then Python will start in interactive mode and run the script for you.
Before using the phycas.sh script, you will need to make it executable:
chmod +x phycas.sh
You may wish to also set up a shell alias to make it easier to run this script from anywhere in your file system. For example, in your $HOME/.bashrc file, you might add this line:
alias p="$HOME/phycas.sh"
The next time you login, you will be able to start Phycas by just typing the letter p!
Test Phycas
Now you should be able to start Python by running your phycas.sh script and begin using the phycas module: for example, type p at the shell command prompt (to invoke the alias you set up in the previous step) and try issuing some Python statements that test whether phycas is working:
p release_version is True ///////////////////////////// ///// Welcome to Phycas ///// ///////////////////////////// Version 1.2.0 Phycas is written by Paul O. Lewis, Mark Holder and David Swofford Phycas is distributed under the GNU Public License (see License file for more information). >>> d = ProbDist.Exponential(10.0) >>> print d.sample()
You can escape from Python using the normal exit key combination Ctrl-D.
Run the test suite
After verifying that everything works, run the test suite to make sure all is well:
cd $HOME/Phycas-1.2.0/phycas/Tests p runall.py
This should produce a lot of output. When it is finished, issue the following command to view the contents of the runall_diffs.txt:
cat diffs.txt
The contents of this file should look like this:
**************************** *** Running ExplorePrior *** **************************** ************************* *** Running SplitTest *** ************************* *********************** *** Running PDFTree *** *********************** *********************** *** Running GTRTest *** *********************** ******************** *** Running Sump *** ******************** ******************** *** Running Sumt *** ******************** ****************************** *** Running LikelihoodTest *** ****************************** *************************** *** Running FixedParams *** *************************** ************************* *** Running Underflow *** ************************* ************************* *** Running CodonTest *** *************************
If errors were encountered, the test output will show the differences between expected and observed output for a particular test.
Note: CodonTest fails on many linux platforms because of a difference in one value at the 7th. decimal place. This is nothing to worry about.
