Installing and building Polyworld from scratch (OLD)

 

IMPORTANT:  Only an up-to-date CVS source checkout should be used (NOT any of the prepackaged source releases).

IMPORTANT:  Polyworld now requires Qt 4.5 or later.  4.6.3 or later recommended.

IMPORTANT:  Currently, only the command-line 'make' build is supported, whether on Mac or Linux.  The Mac Xcode project is no longer functional.

IMPORTANT:  Due to recent changes to the "worldfile" parameter files (and refactoring of visualization, UI, and logging), few if any of the files in polyworld/worldfiles work anymore.  To carry out a test run of Polyworld following a successful build, use an empty worldfile ('touch empty.wf ; ./Polyworld empty.wf').  To see what parameters currently exist and what their defaults are, look at the worldfile schema file:  polyworld/etc/worldfile.wfs.

 

In brief, install your system's developer tools, install the Enthought Python Distribution, install gsl (Gnu Scientific Library), install Qt, do a CVS checkout of the Polyworld source code from SourceForge.net, and build Polyworld either with unix make or Xcode.  For the graphical data analysis tools you'll also need gnuplot.  As straightforward as that sounds, there are more than a few potential gotchas, so detailed instructions are given below.  (Though I've managed to streamline the process considerably for Snow Leopard, Mac OS X 10.6.x, in an academic environment.)

 

Note:  Polyworld is entirely controlled by the parameters in its "worldfile", which must always be specified on the command line via './Polyworld <filename>'.

 

The following notes are outdated, and are only retained in case this functionality is resuscitated:  On Mac OS X, with Xcode, a copy of polyworld/worldfiles/worldfile_nominal will be made to appropriate locations as part of the first build.  On other systems you probably want to do a "cp worldfiles/worldfile_nominal worldfile" prior to running Polyworld.  The worldfile_nominal file is not necessarily a useful environment in which to carry out simulations; rather, it has been designed to exercise most of Polyworld's features.  FYI, the polyworld/worldfiles/worldfile_alifexi_updated is what has been worked with the most recently, carrying out complexity and graph theoretical analyses, and will definitely produce a viable (albeit simple) world and species.

 

Choose your platform:

á      Mac OS X

 

Mac OS X  (largely 10.6 and Intel specific)

 

á      Install latest standard release version of Xcode tools from developer.apple.com

 

Note: Even though Xcode itself is no longer supported, installation of Xcode is required to obtain the necessary gcc-based build environment.

You have to register, but registration is free.

Navigate to "Downloads" and "Developer Tools".

Download latest Xcode .dmg file, double-click to mount, and run the installer.

 

For older versions of Max OS X see the instructions here.

 

á      Download and install the latest LGPL/Free version of the Qt Libraries for Mac from qtsoftware.com

 

You must use version 4.5 or later, as the frameworks have moved to a standard location as of this release, and the Polyworld.xcodeproj now takes advantage of this.

You can now just install Qt's binary libraries; you no longer have to build Qt from source.

The "Framework Only" version is sufficient; you do not need the "SDK: Complete Development Environment".

Just open the .dmg file (if your browser hasn't already opened it), then open the "Qt.mpkg" installer package and let it install Qt binaries in the default locations.

 

á      Download and install the current Academic Enthought Python Distribution

 

This Academic version of the Enthought Python Distribution is free.

You will also need to add /System/Library/Frameworks/Python.framework/Versions/Current/bin to your $PATH.

This gets SciPy and SCons (and NumPy, Matplotlib, and lots of other useful stuff) in one swell foop.

 

This is only available to students and faculty at accredited universities; if you are not in academia you can follow some older instructions here to install SCons and SciPy manually.  Purchasing a copy of one of the other Enthought Python Distributions is also an option, just not a cheap one.

 

á      Download and install gsl (gnu scientific library) from http://www.gnu.org/software/gsl/

 

gsl is free.

gsl is required to build and run Polyworld and to carry out complexity calculations in CalcComplexity.

At least version 1.7 of gsl is required.  gsl-1.14 is current and recommended as of this writing.

 

Due to Snow Leopard (10.6.x) moving to 64-bit compiles by default (-arch x86_64) but the Academic Enthought Python Distribution being 32-bit (-arch i386) only, it is necessary to build both versions of gsl and combine the two architectures into a single fat library.  The easiest way to do this is to download this gsl_build script, place it and the gsl-1.14.tar.gz (or current) archive you downloaded in the directory where you want the source code to live (e.g., ~/src), and invoke ./gsl_build from the command line (don't forget to 'chmod +x gsl_build').  It will do the rest.  Note that the script uses a -O3 level of optimization; I am unaware of any problems using this with recent versions of gsl, but it is something to be aware of should mysterious problems manifest.

 

gsl will be installed in /usr/local/lib, with headers in /usr/local/include/.  If you install gsl somewhere else, such as /sw or /opt using fink or MacPorts, you will have to modify the Xcode project and/or the command-line build tools accordingly, so this standard, non-fink, non-MacPorts install is recommended for gsl.

 

á      Download Polyworld source code from SourceForge.net.

 

The Polyworld source code is free.

 

Download the current working code (usually stable, as it is in constant use) using CVS.  To download the source using CVS, you may either:

 

A) Check out the source anonymously (to someplace convenient, like ~/src), like so:

 

cvs -d:pserver:[email protected]:/cvsroot/polyworld checkout -P polyworld

 

B) Become a Polyworld developer and use your SourceForge.net credentials to check out the source, like so:

 

export CVS_RSH=ssh

cvs -d:ext:[email protected]:/cvsroot/polyworld checkout -P polyworld

                      

(substituting your username for "username").

 

For someone doing development primarily on Polyworld, it is convenient to place the following in your ~/.bash_profile or ~/.bashrc file (or other shell's equivalent):

 

export CVS_RSH=ssh

export CVSROOT=:ext:[email protected]:/cvsroot/polyworld

 

After doing so, checking out Polyworld is as simple as "cvs co –P polyworld".

 

The use of -P is because there are defunct directories, that CVS never discards completely, and the -P option purges these empty directories.  I recommend adding (or editing an existing) ~/.cvsrc and placing the following lines in it:

 

update -Pd

checkout -P

 

This will automatically add the specified options to your cvs update and checkout commands, and will ensure these empty and potentially confusing directories never get created.  With a ~/.cvsrc file containing those lines, and the environment variables defined above in your ~/.bashrc file, checking out Polyworld is as simple as "cvs co polyworld".

 

If you wish to become a developer on the Polyworld project, please contact me at larryy (at) indiana (dot) edu.

 

á      Build Polyworld and associated tools.

 

Traditionally the instructions below would have been valid, but currently the Xcode project is not up to date, so you should stick to building Polyworld from the command line using make.

You can build Polyworld either of two ways, from the command line or in Xcode.

 

A) From the command-line:

 

Go to your polyworld source directory and type "make".  That's it.  Make will place a Polyworld executable in the main polyworld directory and PwMoviePlayer, CalcComplexity, and any other executables in polyworld/bin.

 

B) In Xcode:

 

Launch Polyworld.xcodeproj in Xcode and invoke Build.  That's it.  Xcode will place Polyworld.app, PwMoviePlayer.app, and CalcComplexity in polyworld/build/Development.  Since certain data analysis scripts assume CalcComplexity is resident in polyworld/bin, it is symbolically linked into there, and will overwrite the version built from the command-line, if it exists.

 

I like to keep my build products outside of my source directory, so I have made "build" a symbolic link to a different location.  Xcode lets you put the build products anywhere you want, but by using this technique I was able to leave Xcode set to its default location for build products, which has advantages if you are building different versions of the software from different source directories, while still allowing me to routinely place my build products outside the source directory in my main working environment.

 

Note:  The "Release" Build Configuration does not quite work yet, but will eventually let you build a version of Polyworld that can be installed and run without requiring a user to have Qt installed.

 

NOTE:  The remaining installations are only required for the analysis of data from Polyworld runs, not for Polyworld itself

 

á      Download and install gnuplot.

 

gnuplot is free.

At least version 4.2.0 of gnuplot is required.

Manually download it here:  http://www.gnuplot.info/

 

A special version of readline is required and for OS X 10.6 and later you will need to force a 32-bit build, in order to work with the 32-bit Enthought Python Distribution (and 32-bit aquaterm, if you happen to be using it, though our tools no longer require aquaterm), so do the following:

 

./configure --with-readline=bsd CFLAGS="-arch i386" LDFLAGS="-arch i386"

make

sudo make install

 

For earlier versions of OS X, see these old instructions.

 

á      Download and install bct-cpp (the C++ version of the Brain Connectivity Toolbox).

 

bct-cpp is free.

Information about bct-cpp is here:  http://code.google.com/p/bct-cpp/

Information about the MATLAB Brain Connectivity Toolbox is here:  http://www.brain-connectivity-toolbox.net/

Check out and build the source by entering something like the following:

 

cd ~/src

svn checkout http://bct-cpp.googlecode.com/svn/trunk/ bct-cpp

cd bct-cpp

make

sudo make install

make swig

cp bct.py ../polyworld/scripts/

cp _bct.so ../polyworld/scripts/

 

The final two instructions above assume the bct-cpp directory and the polyworld directory are side by side (for example, in ~/src); adjust accordingly if this is not the case on your system.

 

Linux

 

First install Polyworld's dependencies:

 

sudo apt-get install build-essential xorg-dev libgl1-mesa-dev scons cvs libgsl0-dev libqt4-opengl-dev

 

Then checkout the source from CVS:

 

cvs -d:pserver:[email protected]:/cvsroot/polyworld checkout -P polyworld

 

Build Polyworld using make, copy a sample worldfile for it to read at startup, and give it a try:

 

make

cp worldfiles/worldfile_nominal worldfile

./Polyworld

 

It has been reported that Polyworld has heavy flickering problems while running a window compositing engine, such as Compiz. In Ubuntu, you may want to disable Desktop Effects in System -> Preferences -> Appearance to avoid these issues.

 

For the analysis tools you will also need to install the following dependencies:

 

sudo apt-get install python-numpy python-scipy gnuplot

 

For data analysis you will also need to follow the Mac instructions above for downloading and installing bct-cpp.

 

If the above instructions don't work for whatever reason, you may want to look through the instructions for Mac OS X.  Those instructions accomplish essentially the same thing, except there is no need for the first step (installing Xcode) and you will need to download platform-appropriate versions of Qt, gsl, gnuplot, and SciPy.  (You shouldn't need the --with-readine=bsd option when configuring gnuplot, and aquaterm is Mac only.)  Note that your distribution will likely have blessed packages available for all external libraries listed as requirements. For example, Ubuntu provides an 'scons' package, which should be installed via apt-get rather than downloading/installing from scons.org.  You will use "make" from the command line (though make now relies primarily on SCons) and can ignore instructions related to Xcode.  To use some of the plot scripts you might need to replace 'aqua' with 'x11', although these days we primarily write .eps files rather than drawing to the screen.

 

Windows

 

This still hasn't been fully accomplished, despite some serious effort.  (Note:  There are frank, some would say rude, comments about Windows made in the page at that link.  I've had complaints, but I feel there is valuable information there, and the effort was much appreciated, so the link will stay put until a Windows port is fully successful.  There was hope on this from a different front, but it too crashed and burned.  I think at least part of the problem is that everyone tried to start from Cygwin, but Qt seems to require MinGW which would be better matched with MSYS.)  One of these daysÉ

 

Update:  Though it is still not possible to easily build top-of-tree Polyworld for Windows exactly as it comes, Binh Nguyen has successfully built Polyworld for Windows.  His instructions for doing so are here, and he has placed a revised snapshot of the source code here.  For serious work with Polyworld, be warned that there is a bug in this version that allows neurons to self-terminate, so you may want to diff this snapshot with the current source base and import any differences not needed to keep the build working on Windows, particularly in the brain-related files.

 

 

Old instructions for pre-Snow Leopard Mac OS X and non-academic environments

 

á      Install a version of Xcode tools suitable to your OS release from developer.apple.com

 

You have to register, but registration is free.

Navigate to "Downloads" and "Developer Tools".

Download an Xcode .dmg file, double-click to mount, and run the installer.  (Apple is bad about providing access to older versions of Xcode, but I have had some success using Google to search for Xcode and a specific version, such as [Xcode 3.1 dmg], and been able to track them down that way.)

 

Due to the use of OpenMP for multi-core functionality, if you are using less than Mac OS X 10.6 (Snow Leopard) and Xcode less than version 3.2, you will have to repoint the C and C++ compilers to version 4.2 (instead of 4.0).  To do this type the following (and provide your password when prompted):

 

cd /usr/bin

sudo ln -sf g++-4.2 g++

sudo ln -sf c++-4.2 c++

sudo ln –sf gcc-4.2 gcc

 

If you are still using Tiger (10.4.x) you can download and install gcc 4.2 using the file and instructions at http://r.research.att.com/tools/#gcc42, and type:

 

sudo gcc_select 4.2

 

However, Xcode itself cannot currently be used to build Polyworld on Tiger because it does not support gcc 4.2.  (You could conceivably tell Xcode to use gcc 4.0 and remove the –fopenmp compiler option and get Xcode to build Polyworld on Tiger, but there are no guarantees.)

 

á      Download and install fink / FinkCommander

 

FinkCommander and fink are free.

fink is useful for installing other needed components and, conveniently, it installs a fully functional version of readlink.

readlink is needed for command-line builds and post-simulation data analysis scripts.

Mac OS X has long come with a version of readlink that is borderline useless due to GPL constraints on the original source.  Our command-line build system currently requires a more capable version of readlink, which you will get automatically with fink.

 

You'll need to have /sw/bin and /sw/sbin in your $PATH (which should be taken care of automatically by the invocation of /sw/bin/init.sh in your .bashrc or other suitable login file, per the fink installation instructions).

 

Note:  If you're running 10.6.x (Snow Leopard), you'll need to build and install fink from source.  Code and instructions can be found at http://www.finkproject.org/download/srcdist.php.  Initial experimentation also suggests FinkCommander does not work with 10.6 even if built from the latest CVS source (it always shows zero packages available, no matter how updates are performed), so you must also perform command-line fink installs.  Fortunately this is trivially simple once you have followed the fink installation instructions on the indicated web pages, as you need only type fink install <package_name>.

 

Update:  It appears that if you set the system-wide perl to an earlier version you can get FinkCommander to work on 10.6.x.  I don't recall the details, but knowing that this is a perl version issue should let you find the solution with a minor amount of web searching.

 

á      Install the latest SCons using fink / FinkCommander or by downloading from scons.org

 

SCons is free.

Note: This step is only necessary if you will be building from the shell rather than Xcode.

You must use version 1.2 or later.

 

Assuming you installed fink and FinkCommander above, you can install "scons" using FinkCommander.  To install using fink on 10.6.x (where FinkCommander doesn't work), type fink install scons.

 

Alternatively, you may install SCons directly by downloading a tarball, such as scons-1.2.0.tar, to your ~/Downloads directory, and executing the following (or similar) commands in a terminal session:

 

cd ~/Downloads

tar -xf scons-1.2.0.tar

sudo python scons-1.2.0/setup.py install

rm -rf scons-1.2.0*

 

á      Install aquaterm, gnuplot, and Scipy.  (These are only needed for the graphical data analysis tools, not for Polyworld itself.)

 

10.4 and earlier only:  If you are using a version of Mac OS X prior to Leopard (10.5), you will probably have to install X11 from your original Mac OS X installer disc, which you can do using the "Optional Installs.mpkg".  You will also need to install a modern version of Python such as is available from MacPython.org.

 

These open source packages are free.

At least version 4.2.0 of gnuplot is required.

Manually download and install these packages from here:

https://sourceforge.net/projects/aquaterm/

http://www.gnuplot.info/

http://macinscience.org/?page_id=6  (Chris Fonnesbeck's Scipy Superpack)

 

Install aquaterm before configuring gnuplot, so support for aquaterm will be built in.  (Note: More recent versions of the graphics tools write to a .eps file instead of exporting to aquaterm, so you can skip the aquaterm installation entirely if you want, but if you want the possibility of using aquaterm it should be installed before configuring gnuplot.)

 

On OS 10.5 or earlier, this should suffice to configure gnuplot before you build and install it:

 

./configure --with-readline=bsd

 

On OS 10.6 and later, you will need to force a 32-bit build, in order to work with 32-bit Aquaterm, so use:

 

./configure --with-readline=bsd CFLAGS="-arch i386" LDFLAGS="-arch i386"

 

gnuplot will be installed in /usr/local/lib, with headers in /usr/local/include/.  (If you install it elsewhere you may need to adjust for that fact.)

 

Non-Mac developers can obtain SciPy from http://www.scipy.org/.