Installing
and building Polyworld from scratch
WARNING:
Only an up-to-date CVS source checkout should be used (NOT any of the
prepackaged source releases).
WARNING:
Polyworld now requires Qt 4.5 or later. 4.6.3 or later recommended.
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.)
Important Note:
Polyworld is entirely controlled by the parameters in a file called
"worldfile", looked for adjacent to the executable in the file system
(or inside the application bundle).
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.
á Mac OS X
á
Linux
á
Windows (does not work automatically yet,
but has been made to work)
Mac OS X (largely 10.6
and Intel specific)
á
Install latest standard release
version of Xcode tools from developer.apple.com
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:anonymous@polyworld.cvs.sf.net:/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:username@polyworld.cvs.sf.net:/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:username@polyworld.cvs.sf.net:/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.
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:anonymous@polyworld.cvs.sf.net:/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.
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://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/.