These instructions assume you have downloaded the relevant Biodiverse release and saved it to your hard drive.

They also apply to version 0.12, the current release as of 07Dec2009.

• Update an existing installation
• Windows 32-bit
• Executable version
• Source code
• Macintosh
• Mac trouble shooting
• Linux and UNIX

Update an existing installation

• Rename the existing Biodiverse installation to something like Biodiverse_old or Biodiverse_0.9.1127 (or whatever the last version number was).
• Unzip the new Biodiverse folder and rename it to whatever you were using before, e.g. C:\Biodiverse on Windows.
• Run the system as previously. It should work, as all the path names are the same as before.
• Delete or retain the previous installation as best suits your needs. You should obviously take care if you edited any of the files or added new files in that folder.

Windows 32-bit

• The windows distribution now includes the GTK binaries so there is no need for additional downloads for the executable version. Perl is still needed for the source code version.

Executable version

• Unzip the biodiverse directory onto your hard drive. These instructions assume you have placed it in C:\Biodiverse, but it can go anywhere on the file system. If you have an existing installation then move it out of the way first (rename it).
• Biodiverse can be run by double clicking on C:\Biodiverse\bin\BiodiverseGUI_win32.exe

You can associate .bps, .bds, .bms and .bts files with the BiodiverseGUI_win32.exe file if you want to double click on a Biodiverse file to open it. (.bpy files are currently supported, but are scheduled for deprecation). See DataStructures#File_naming_scheme for an explanation of the file names.

Source code

Use this approach if you want to debug the source code and provide patches, etc. You can still use the executable version if you use this installation.

• Unzip the biodiverse directory onto your hard drive. These instructions assume you have placed it in C:\Biodiverse, but it can go anywhere on the file system.
• Edit your system's PATH variable to include C:\Biodiverse\bin and C:\Biodiverse\gtk\bin. For an example of how to do this, see http://www.computerhope.com/issues/ch000549.htm.
• Download and install Perl 5.8.925 from http://downloads.activestate.com/ActivePerl/Windows/5.8/ActivePerl-5.8.9.826-MSWin32-x86-290470.msi .

• Once that's done, copy and paste the following commands into a command window. These install additional perl libraries needed by Biodiverse. Note that this assumes you don't already have ppm repositories defined. If you do then disable the trouchelle repository for the first three sets, as its gtk libs don't install properly (when last I checked).

ppm install Pod-Simple
ppm install PadWalker

ppm repo add http://voltar.org/active/5.8
ppm install http://voltar.org/active/5.8/Gtk2.ppd

ppm repo add http://www.biodiverse.unsw.edu.au/ppm
ppm install http://www.biodiverse.unsw.edu.au/ppm/Geo-Shapelib.ppd
ppm install http://www.biodiverse.unsw.edu.au/ppm/Gnome2-Canvas.ppd
ppm install http://www.biodiverse.unsw.edu.au/ppm/Statistics-Descriptive2.ppd
ppm install http://www.biodiverse.unsw.edu.au/ppm/Gtk2-GladeXML.ppd

ppm repo add http://trouchelle.com/ppm/
ppm install Data-DumpXML
ppm install Math-Random-MT-Auto
ppm install Devel-Symdump
ppm install Text-CSV_XS
ppm install DBD-XBase
ppm install IO-Stringy
ppm install HTML-QuickTable
ppm install YAML-Syck
ppm install Data-Structure-Util

You should now be able to run Biodiverse by executing C:\Biodiverse\bin\BiodiverseGUI.bat (or C:\Biodiverse\bin\BiodiverseGUI.pl if your system runs Perl files when they are opened).

Macintosh

The current Mac install requires a source code installation. We are working on a standalone executable, or at least one that bundles all the relevant dependencies.

• First, you must have the X11 software on your Mac. You will have this if you have Leopard or later. If you have a previous OSX you will need to obtain it either from your original CD or from the Apple site.

• Next, install MacPorts (unless you already have it).
• If your operating system is Snow Leopard then use http://distfiles.macports.org/MacPorts/MacPorts-1.8.1-10.6-SnowLeopard.dmg
• If your operating system is Leopard then use http://distfiles.macports.org/MacPorts/MacPorts-1.8.1-10.5-Leopard.dmg
• (If needed, the generic MacPorts URL is http://www.macports.org ).
• Double click on the dmg file contents to install. This will produce a folder called “opt” on your hard drive which has the components needed to perform the following steps.
• If you already have MacPorts installed then run this command in a terminal window to get the latest versions.

sudo port -v selfupdate

• You now need to install a number of ports. Open a terminal window and copy and paste the following commands one after the other. You could copy and paste all of them at once, but the commands can take a while (Gtk takes 30mins+) and download a large number of dependencies. Doing them one at a time makes it easier to keep track of which one you're up to.

sudo port install gtk2
sudo port install p5-gtk2
sudo port install p5-gtk2-gladexml
sudo port install p5-gnome2-canvas
sudo port install p5-yaml-syck

• You now need to install the following perl libraries using the “cpan” program that comes with perl. To install these, open an X11 terminal window and type:

sudo /opt/local/bin/cpan

Follow the appropriate prompts to set up cpan. If you are asked if you want cpan to install automatically, choose YES. It should be all defaults if you are asked any questions.

Once cpan is ready, install the following libraries individually, by copying and pasting them one by one and hitting return after each. Wait until each is installed before going on to the next one (this is again for keeping track).

install Data::DumpXML
install Math::Random::MT::Auto
install Devel::Symdump
install Pod::Simple
install Text::CSV_XS
install DBD::XBase
install IO::Stringy
install HTML::QuickTable
install Geo::Shapelib
install YAML::Syck
install PadWalker

• Now you are ready to install Biodiverse. Extract the biodiverse source code zip file to somewhere on your hard drive, eg your home folder.
• To run Biodiverse, open a terminal window and change directory to the Biodiverse/bin folder. If it is in your home folder and called Biodiverse then type:

cd ~/Biodiverse/bin

• Once you have done this, type the following to open Biodiverse:

/opt/local/bin/perl BiodiverseGUI.pl

You can dispense with the /opt/local/bin text if you are using the first perl in the search path. To check if it is, type:

which perl

If it returns /opt/local/bin/perl as first in the list then you can dispense with the /opt/local/bin and type

perl BiodiverseGUI.pl

Mac trouble shooting

• If Perl complains that it cannot locate a file when running Biodiverse then this library will need to be installed using the cpan method. The complaint will look like Can't locate Fred/Fred.pm in @INC (@INC contains:...) In this case, install module Fred::Fred (substitute a double colon “::” for each forward slash “/”, and remove the trailing “.pm” from the module it cannot locate).
• If the sudo port install commands do not work then you need to have read & write access for all the contents of the /opt folder. To do this, open the info tab for the opt folder, under “Sharing & Permissions” change all to have read & write preferences. Directly below, there is a small cog button, which has the option to “apply to enclosed items”. This will mean you have ownership of all the sub folders in /opt.
• MacPorts might also complain that files are out of sync, probably if you have an existing MacPorts installation. If this is the case then run this command to ensure all files are up to date.

sudo port -v selfupdate

Linux and UNIX

• These instructions are vague as we have not fully tested them.
• Install GTK using your distribution's package manager. Make sure you install Glade as well. Actually, if you install Glade then it should collect all its dependencies, which includes the rest of GTK if it is not already installed.
• Linux probably comes with Perl, but install it if it is not already there.
• Next, install all the modules listed for the Macintosh using the CPAN tool that comes with Perl. The list in the cpan section of the Macintosh instructions is likely to be correct, but there might be others. Apart from the Gtk2::Glade lib, the only suggestion is to run Biodiverse and install the modules it fails on not finding (see the #Mac_trouble_shooting section). This will take a while until it works. Make sure you install dependencies to save time installing further modules.

Please let us know so we can document it.