Developer Manual

Home News Downloads Tutorials User Manual Reference Manual Developer Manual Forums Team Members Future Work FAQ Links

Installing Topographica with version control Version control allows you to keep up to date with the latest changes made by other developers, and allows you to keep track of your own changes. Topographica's source code is held in a central Subversion (SVN) repository on SourceForge.net; the repository contains the files making up Topographica itself, plus source code versions of most of the various external libraries needed by Topographica. The first step to installing a version-controlled copy of Topographica is to obtain a copy of this repository, either by using SVN as described in our SVN instructions, or by using an alternative version control system that can interact with SVN. We ourselves also use and support the distributed version control system Git; developers who wish to use this should instead follow our git instructions. Once you have obtained the version-controlled topographica directory, you need to install Topographica's dependencies. There are two options for this. The first is to install the required dependencies yourself (e.g. using your system's package manager). The second is to use the Makefile to build all Topographica's dependencies. If your system has a good package manager, you may wish to use the first option, but the second option is frequently tested and uses versions of external packages that we know to work well together. (1) Installing Topographica's dependencies on your system Binaries of Topographica's dependencies are available for many platforms, and many package managers (e.g. apt-get on Ubuntu or Macports/Fink on Mac) also include them. You will need to install at least Python, NumPy and PIL, and preferably MatPlotLib, gmpy, SciPy, and IPython as well. Once you have installed those on your system, you can type make OTHER_PYTHON=/path/to/python topographica-other-python, where /path/to/python is the location of the copy of Python for which you have installed Topographica's dependencies (and defaults to /usr/bin/env python if not specified). This will create a topographica script that uses the specified copy of Python. Note that you should not run setup.py, since that would install Topographica into your system's Python directory, whereas we want to use the version-controlled directory. Also, you can delete the external directory, since you have already installed the external dependencies. Now you can skip to the after installation section below. (2) Build all Topographica's dependencies Building Topographica's dependencies is usually straightforward on Mac and Linux. Before beginning, you need to ensure your system has the prerequisites described below. Mac OS X Building Topographica on OS X should be straightforward. Assuming you are using OS X 10.6 (Snow Leopard), you need to install Apple's Xcode3 if your system does not already have it. Xcode provides the required GCC C/C++ compiler (among other development utilities). You can then follow the instructions below for building Topographica. Linux Most Linux systems will already have the required libraries installed, so usually no action will be required here. On some Linux distributions that start with a minimal set of packages included, such as Ubuntu or the various "live CD" systems, you may need to specify explicitly that some standard libraries be installed in your system if you want to use the GUI, including libx11-dev and libxft-dev. Note that on some systems the -dev packages are called -devel, and sometimes specific versions must be specified. Example for Ubuntu 9.10: sudo apt-get install libx11-dev libxft-dev Once these libraries are installed, you can proceed to the Building instructions below. Building Topographica The instructions below assume you have followed any necessary platform-specific instructions described above. You will need a writable directory with approximately 1.2 GB of space available (as of July 2010). Enter the directory where topographica is located and type make (which may be called gmake on some systems). It is best to do this as a regular user in the user's own directory, not as a root user with special privileges, because Topographica does not need any special access to your system. The build process will take a while to complete (e.g. about 10 minutes on a 3 GHz Core 2 Duo machine with a local disk). If you have problems during the build process, try adding -k to the make command, which will allow the make process to skip any components that do not build properly on your machine. Topographica is highly modular, and most functionality should be accessible even without some of those components. optional: If desired, you can also make local copies of the HTML documentation from the web site. To do so, you must have the php, bibtex, convert, and fig2dev commands installed; type make all instead of (or after) make. (If you don't have those commands, in most distributions you can get them by installing the php5-cli, tetex, imagemagick, and transfig packages). make all will also run the regression tests and example files, to ensure that everything is functioning properly on your system. If building was successful, a script named topographica will have been created in the topographica directory, and you can proceed to the after installation section below. After installation To launch Topographica itself, you can enter ./topographica -g (or just ./topographica for no GUI) from within the version-controlled topographica directory, or else enter the full path to the script. For actual use, you will probably want to add a symbolic link in a directory that is in your regular path, pointing to the topographica script. The instructions elsewhere in the documentation assume that you have done so, so that you only need to type topographica instead of cd /path/to/topographica ; ./topographica. You can check that Topographica is working as expected by running make tests within the topographica directory. If you do the tests on a machine without a functioning DISPLAY, such as a remote text-only session, there will be some warnings about GUI tests being skipped.

Hosted by: James A. Bednar (jbednar@inf.ed.ac.uk) Last update: Thu Aug 5 15:21:42 BST 2010.