Installing and building Polyworld from scratch

 

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

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. There may also be couple of valid, modern day worldfiles in the sandbox directory.

 

Between AppleÕs change to clang/llvm (from gcc) in Mavericks (10.9), their addition of crucial modules to the built-in Python (like SciPy and NumPy), major changes to the Qt distribution, and new licensing policies from Enthought, there has had to be a substantial change in the methods for building Polyworld on a Mac.  Below are instructions that have reliably worked for Mavericks (OS X 10.9) and Qt 4.8.x.  (Polyworld built using the more recent Qt 5.x will run, but produces a reduced size rendering in the main window, for reasons not currently known.)  Instructions for older versions of OS X (and Qt) are here.

 

In brief, install your system's developer tools, install Qt, install gsl (Gnu Scientific Library), install scons, install cvs (via homebrew), install gcc, do a CVS checkout of the Polyworld source code from SourceForge.net, and build Polyworld from the command line using make.  For the graphical data analysis tools you'll also need gnuplot.  There are some potential gotchas, so more detailed instructions are given below.

 

Note:  Polyworld is entirely controlled by the parameters in its "worldfile", which must always be specified on the command line via './Polyworld <filename>'.  The simplest way to test Polyworld after successfully building it is to use an empty worldfile (touch empty.wf ; ./Polyworld empty.wf).  Unfortunately, due to sweeping changes in the worldfile syntax, none of the files in polyworld/worldfiles/ work any longer (though the very few with a .wf extension may be close enough to give a hint about barrier definitions and such).  The only guaranteed working worldfile currently checked in is polyworld/sandbox/social/feed_young.wf.  The available worldfile parameters can be seen in polyworld/etc/worldfile.wfs, the worldfile schema.

 

Choose your platform:

 

Mac OS X  (largely 10.9 and Intel specific)

 

•      Install latest standard release version of Xcode tools using the App Store application.

 

Note: Even though Xcode itself is no longer supported, installation of Xcode is required to obtain the necessary development tools.

Launch Xcode once so it can install some needed components.

 

•      Create a link to the current OS X SDK include files in the standard unix location.

 

Note: This step may not be necessary; check to see if you already have a populated /usr/include before doing the following.

In Terminal type:

sudo ln -s $(xcrun --show-sdk-path)/usr/include/ /usr/include

 

•      Download and install Qt 4.8.x for Mac from qt-project.org.

 

The default, non-commercial installation is fine, however, I recommend you comment out lines 330-332 of /Library/Frameworks/QtCore.framework/Headers/qglobal.h to eliminate a zillion warnings.

 NOTE: This is not the latest, which is 5.3.0 as of this writing.  If built with Qt 5.3.0 the code will run, but produce a reduced size rendering in the main window, for reasons not currently known.

 

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

 

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

gsl-1.16 is current and recommended as of this writing.

 

Due to modern Mac OS performing 64-bit compiles by default (-arch x86_64) but some Python distributions being 32-bit (-arch i386) only, it is recommended 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.16.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: It is important that the downloaded archive be of the form *.tar.gz for the gsl_build script to work.  If the download is automatically decompressed, just re-compress it with gzip.)  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 command-line build tools accordingly (probably polyworld/scripts/build/SConstruct and polyworld/scripts/build/scons_util.py).

 

•      Download and install scons from http://www.scons.org/download.php.

 

Decompress and untar the archive, cd into it, and type Ôpython setup.py installÕ.

 

•      Download and install homebrew from http://brew.sh.

 

That is:

ruby -e "$(curl -fsSL https://raw.github.com/Homebrew/homebrew/go/install)

 

Do as it asks and allow the Xcode command line tools to be installed.

If you run Ôbrew doctorÕ, as suggested, donÕt worry about the libgsl*.a and libutils.a libraries you installed on purpose when you installed gsl.

 

•      Install cvs.

 

By typing:

brew tap homebrew/dupes

brew install cvs

 

(Yep, Apple no longer installs cvs with its developer tools.  Guess itÕs time to switch to git, but for now thisÕll do.)

 

•      Download and install current gcc from http://hpc.sourceforge.net.

 

Download gcc-4.9-bin.tar.gz, then type Ôsudo tar -xzvf gcc-4.9-bin.tar.gz -C /Õ.

 

•      Download Polyworld source code from SourceForge.net.

 

Download the current working code (usually stable) 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 SourceForge 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) pobox (dot) com.

 

•      Build Polyworld and associated tools.

 

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.

 

You may need to adjust the path to your Qt libraries, as they keep moving from release to release; if so, I suggest the else clause around line 115 in scripts/build/scons_util.py. Similarly, you may need to adjust the path to g++; if so, go to the env['CXX'] and env['CC'] declarations around line 160 in scripts/build/SConstruct. Sorry for the hassle; someday I'd like to make this more automated and robust.

 

There will also be a polyworld/src directory created, consisting of nothing but symbolic links to source files, providing a convenient way to grep through the source code for anything you might want to find, without wasting time grepping through run directories, executables, etc.  Just type Ôgrep –r <search_term> srcÕ (from within the polyworld directory).

 

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

 

•      Download and install gnuplot from http://www.gnuplot.info/.

 

At least version 4.2.0 of gnuplot is required.

 

A special version of readline is required, as shown:

 

./configure --with-readline=bsd

make

sudo make install

 

For older 32-bit Python installations you would have to add CFLAGS="-arch i386" LDFLAGS="-arch i386" to the ./configure step.

 

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

 

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).  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.