To run the tests, 'cd tests && python runtest.py -B'; omit -B to use in-place code instead of the build directory. runtest will fail out if it cannot import pygr from within the working directory, to avoid running the tests on the installed version.

Overview

Generally speaking, the following steps must be taken to build and install Pygr on your machine:

1. Install Python
2. (for Git sources only) Install Pyrex
3. Install a C compiler and other development files
4. (optional) Install modules providing MySQL/SQLite support
5. (optional) Install BLAST tools
6. Build/install Pygr
7. Test your build

Installing Python

This should be pretty straightforward. For ready-to-use binaries look to either your system's package repository (Linux, BSD, Fink, Cygwin, ...) or installers provided at Python.org (Windows, Mac OS X). If all else fails, you can always try building Python from source.

Pygr should work correctly with any version of Python between 2.3 and 2.6, inclusive. Python 3.0 is not supported and no conversion has been planned yet, primarily because even its latest version (3.0.1) exhibits visibly worse I/O performance than the 2.x branch.

Installing Pyrex

Pygr extension code is written in Pyrex rather than plain C, making it necessary to have Pyrex code translated into C before the compiler can do its job. Official Pygr packages come with pre-build C files so if you want to install one of these, you may skip this step. Conversely, you will need Pyrex installed to build Pygr using the code from our Git repository.

Pyrex hasn't been officially declared finished yet, which means two things to Pygr users: one is that you'll want the latest available version (as of now, 0.9.8.5) in order to avoid bugs, the other is that unless your system's software repositories contain new-enough Pyrex packages (many do - look for pyrex or python-pyrex), you'll need to build the module by hand. Fortunately the latter is very easy:

• download and unpack the archive;
• launch a command-line interpreter and enter the newly-created directory;
• run python setup.py install, possibly adding the option -O if you want optimised files to be installed too. You may need to be more specific than saying just python if multiple versions are present and/or the main executable is not in the path. Last but not least, install copies files into sytem-wide Python directories so superuser privileges (or at least write access) might be needed to run it, in particular under Linux/Unix.

In case of Pygr Pyrex is only required at build time, it can safely be removed afterwards.

The C Compiler etc.

Pygr is not a pure-Python module and a C compiler, along with possible assistant tools, must be present at build time for it to finish successfully. You will also need Python's header files. How all these should be obtained depends a lot on the system you use:

• if you built Python from source, you should already have everything;

• if under Linux/Unix/Fink/Cygwin/..., Python's header files may be distributed separately from its executables and other run-time files. Look for something similar to python-devel in your package manager; installing it should automatically pull in all dependencies. As for the compiler, you will most likely use GCC - almost certainly available in your system's package repositories, if not already on your hard drive;

• under Windows, your Python installation should come with all the required header files but things are more complicated when it comes to the compiler. There are two options available here, discussed in more details here:
• use Microsoft Visual C++ and the official Microsoft Platform SDK; or
• use MinGW, port of GCC and friends to Windows bundled with freely-distributable standard header files and import libraries.

Like Pyrex, both the compiler and the header files are build-time dependencies only. They can safely be removed afterwards.

MySQL/SQLite Support

The following Python modules must be present in your system in order for Pygr to support accessing MySQL and SQLite databases:

• SQLite - sqlite3 (part of the standard library) for Python 2.5 and newer, pysqlite2 (pysqlite-2.x.y) for older versions;

• MySQL - MySQLdb (from the MySQL-python package).

Both are fairly common in package repositories, and if all else fails they can be built from the source the same way as Pyrex (then again, note that building mysql-python is more complicated than most Python modules, especially under Windows - see here for details of the latter case).

Note that Pygr only checks for SQL-related modules at run time - they needn't be present at the time of installation.

BLAST Support

Pygr uses standard command-line BLAST tools to provide BLAST support. To have this work:

• Download the tools;

• Unpack them somewhere;

• Add the bin subdirectory of wherever you unpacked the tools to to the search path.

Just like with SQL modules, Pygr only looks for BLAST tools at run time.

Building and Installing Pygr

If you want your Pygr installation to be system-wide, the procedure is exactly the same as for Pyrex - obtain the sources, enter the directory and run python setup.py install (possibly with -Ox). If however your installation is only to be local, you've got two options:

• run python setup.py build. This will prepare a local directory containing a clean and complete build of Pygr but stop short of copying its contents to a system-wide location; you can then copy these contents by hand to wherever you want them to be and as long as you specify this directory in sys.path, Python will be able to find Pygr - and other modules which may be installed in it - there. You will find this build in the system-dependent directory build/lib.OS-ARCH-PV, e.g. build/lib.linux-x86_64-2.5. After you're done, the Pygr sources can safely be deleted;

• run python setup.py build_ext -i. This will perform a so-called in-place build, i.e. build C extensions of Pygr in the source directory. This approach is obviously not recommended for long-term use (one needs to keep the sources around, conflicts can arise between different Python versions, etc.) but facilitates having a quick look at Pygr - in particular, if you launch your Python interpreter or script from the directory containing setup.py, in-place Pygr code should be imported automatically i.e. without having to set sys.path.

Testing Your Build

Source packages of Pygr come with a test suite which allows one to verify that your build runs correctly. To run then, cd to the subdirectory tests and run python runtest.py -B if you ran build or install earlier, or python runtest.py if you created an in-place build.

Note that the test suite will abort if it cannot find appropriate files locally, i.e. in either the build subdirectory or in place - even if the very same version of Pygr is already present in Python path. This happens by design to avoid version mismatches between Pygr and the test suite.

Running the tests will display some information pertaining to their progress, followed by a summary. If everything is right, all tests should pass. Depending of what optional components are present in your system you may observe some test suites having been skipped.

For details about testing on Windows, see PygrOnWindows.

Packaging

Instead of installing Pygr into the local Python package tree using install one may opt to create an appropriate package and either install the package instead (e.g. to have Pygr under the control of a package manager) or share it with users who for either can't or don't want to build Pygr from source. A wide selection of binary packages of Pygr can be found on our Downloads page; to find out how to create packages of different formats or to learn more about how we build the provided ones, see the PackagingPygr Wiki page.

Known Issues

The setup script fails to invoke Pyrex correctly under Python 2.3/2.4 if setuptools are installed. Specifically, the following condition must be met for this bug to trigger:

• building Pygr for Python 2.3/2.4;
• setuptools are installed and get imported correctly;
• Pyrex-generated .c files are not present or are older than respective .pyx files.

This appears to be a bug in setuptools; we have confirmed it to be present in version 0.6c9 of the package. Note that this problem should not affect users installing packaged releases of Pygr, as these are shipped with pre-built .c files and thus do not invoke Pyrex.