  
Instructions for Compiling & Running DESpot Application
=======================================================
         
This guide contains instructions on how to compile DESpot under Linux,
Mac OS X and Windows.  The Linux instructions are directly below, followed by
the Mac OS X and then  the windows instructions.

You need to use at least QT 4.5.0 to compile DESpot.  DESpot has been
well tested against QT 4.5.2.  If at all possible, you  should use
this version.  However, DESpot should work fine with later versions of
QT such as 4.6.x or 4.7.x.

Once compiled, you can access DESpot's online help browser. From
DESpot, see the "Help > Help contents" to bring up DESpots online 
help.  This will prvoide detailed information on DESpot's capabilities,
and how to use them.


+++++++++++++++++++++++++++++++++++++++++++++++++++++++

LINUX INSTRUCTIONS

+++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
You should make sure the QT development packages are installed.  For
Fedora Linux, the rpms are called: qt-devel 
You should use your distribution's package manager
to install the package (i.e. yum or yumex for Fedora).

You should also make sure you have the C++, g++, compiler installed.
For Fedora Linux, the RPM is called: gcc-c++ 


Steps to compile DESpot using command line 
------------------------------------------
0.  Download the latest tar file of DESpot, as well as the linux
version of the BuDDy  BDD libraries (buddy-2.4Lin.tgz).

1. untar the DESpot  source code that you downloaded 

If the file was "DESpot 1.0.10.tgz"  run the command:

tar xvzf DESpot 1.0.10.tgz

2. untar the BuDDy source code:

tar xvzf buddy-2.4Lin.tgz

3. Configure and compile the BuDDy libraries.    In the buddy-2.4
directory, run as root:

./configure --libdir=/usr/lib --includedir=/usr/include

then:

make

then:

make install

----------------------------------------------------------
If you wish to enable Distributed Tools, skip ahead to 
'Alternate Steps for Distributed Tools' below. Otherwise, 
continue with step 4.  Note, unless you need a distributed
version, it is recommended you avoid the additional complexity
 of  compiling and running an MPI version, and instead compile the
 default version below. 
----------------------------------------------------------

4. From the DESpot source directory run:

qmake-qt4 DESpot.pro

Note that on some Linux distributions there may not be a qmake-qt4
command, but just a "qmake".

5. then type: make release

 This produces the DESpot binary in the release folder.  If you have 
a multicore cpu (say n cores), you can speeds things up by using 
"make -jn release" to run n compile threads.

 Note: If you are getting strange error about MPI at this point, check
 CommonDefinitions.h to see if the line #define __ENABLE_DIST__ is uncommented.
 If it is, comment it out, save, and let Dr. Leduc know that the line has 
 been checked in uncommented.

6. switch to the release directory: cd release

7. to start DESpot, type: ./DESpot

You should be able to safely copy the DESpot binary to another
directory, but not to your home directory as DESpot will create a
"DESpot" subdirectory (for configuration) in your home directory.


Alternate steps for Distributed Tools
---------------------------------
++NOTE++: Steps 0-3 from above, and steps 4-6 below will need to be performed
on the master system as well as each slave node. 

++NOTE 2++: The distributed processing requires that the DESpot
projects you wish to check be located along the same path on each
system (master and slave nodes).  The slaves will load the project
files and DES, so the master and slave nodes should have a shared
network filesystem.  This can be accomplished through a
NFS, or equivalent setup. 

++NOTE 3++: For the distributed processing, you must configure your
systems such that you can ssh between them without being prompted for
a password. 

4. Install OpenMPI 1.5.4 or later. DESpot has been tested against version 1.5.4
   so, if at all possible, use that version. Version 1.4 should still work, but
   DESpot has not been tested against it.  Make sure  the master and
   all slaves have the same version installed. 
   
5. Add the path to your OpenMPI bin directory to your PATH variable.

   For example, if you installed OpenMPI to '/usr/lib/openmpi', you
   will want to add '/usr/lib/openmpi/bin' to your PATH, without
   the quotes. This addition must persist between logins, so you will
   need to add it in your .bashrc file, or equivalent.
   
6. Add the path to your OpenMPI lib directory to your LD_LIBRARY_PATH variable.

   For example, using the same install path as in 2., you will want to add
   '/usr/lib/openmpi/lib' to your LD_LIBRARY_PATH, without the
   quotes. This addition must persist between logins, so you will need
   to add it in your .bashrc file, or equivalent.

++NOTE 4++  Sometimes when openmpi libraries are installed, the
library locations are not added to the ldconfig config files. If the
system is failing to find the libraries, this may be the case.  For
Fedora, you can (as root user) add a file to the /etc/ld.so.conf.d
directory (called say: openmpi.conf) containing the location of the
openmpi libaries (for example: /usr/lib64/openmpi/lib/). You then must
run (as root) the "/sbin/ldconfig" command.   
   
   To build the Master application:
   --------------------------------
7a. From the DESpot source directory run:

    qmake-qt4 mpi=1  DESpot.pro
	
	Note that on some Linux distributions there may not be a qmake-qt4
	command, but just a "qmake".
	
8a. then type:

	make release
	
	This Produces the DESpot binary in the release folder.  If you have 
    a multicore cpu (say n cores), you can speeds things up by using 
	"make -jn release" to run n compile threads.
	 
9a. Ensure that your firewall is set to allow all communications
	 between your local system and the remote nodes you wish to use. 
	 
10a. To start DESpot, switch to the DESpot release directory: 

     cd release
	 
	 from the DESpot source directory
	 
11a. And type ./DESpot
	
12a. Set up the hostfile within DESpot:

	 Open or create a new project. Select 'Distributed Tools',
	 then 'Configure Distributed Processing'.
	 
13a. Add (or edit) your remote nodes using the large
	 textbox. If you wish a node to have multiple slave
	 applications spawned on it, just enter that node 
	 on multiple lines (one for each slave process you wish
	 spawned). This is useful  if your slave nodes have multiple
	 cpus. These duplicate node entries should be listed after the
	 other nodes in order to better optimize the distribution. 
	 
	 ++NOTE++: If you only use only localhosts, you will get a
	 multithreaded version of DESpot. 
	 
	 ++NOTE++: Any time you add or edit this list of nodes you
	 MUST restart DESpot for the changes to take effect.
	 
14a. Click Ok and restart DESpot (if you edited the list of nodes).

	 DESpot is now configured for Distributed Processing.
	 
	 You should be able to safely copy the DESpot binary to another
	 directory, but not to your home directory as DESpot will create a
	 "DESpot" subdirectory (for configuration) in your home directory.
	
	
   To build the Slave application
   ------------------------------   
++NOTE++: If your remote nodes run a different Linux distribution
   (including version number) than    the master system, you must
   compile the slave application on that distribution. 
   
7b. From the DESpot source directory run:

    qmake-qt4 slave=1 DESpot.pro
	
	Note that on some Linux distributions there may not be a qmake-qt4
	command, but just a "qmake".
	
8b. then type:

	make release
	
	This Produces the DESpotMPISlave binary in the release folder.
    If you have  a multicore cpu (say n cores), you can speed things
    up by using "make -jn release" to run n compile threads.

9b. Add the path to the slave application to your PATH variable.

	 For example, if your DESpotMPISlave binary is located in
	 '/user/home/DESpot/release', you'd need to add that location
	 to your PATH, without the quotes. This addition must persist
	 between logins, so you will need to add it in your .bashrc
	 file, or equivalent. 
	 
10b. Ensure that your firewall (on the master and each slave) is set
	 to allow all communications between each node you perform
	 these steps on and the master system. 

++NOTE++: your Makefiles are currently set to produce slave binaries.
I recommend that now     "qmake-qt4 mpi=1  DESpot.pro"  to reset them
to make the main DESpot binary.  Otherwise, if you make a chancge and
recompile only the slave binary gets relinked.

++NOTE++:  You can also use the bash script "makeDESpotMPI" found in
the DESpot source directory, but you will need to edit it to suit your
situation.  The script will run the qmake and make commands to compile
the release version of the main and slave application, and then copy
the save binary to $HOME/bin.  You can also pass in the number of
threads to use for compilation.


+++++++++++++++++++++++++++++++++++++++++++++++++++++++

Mac OS X INSTRUCTIONS

+++++++++++++++++++++++++++++++++++++++++++++++++++++++

These instructions are very similar to the Linux instructions so
first read them and then continue to read below.  We will only provide
the steps that are different.

WARNING:  Do not follow the Linux alternate instructions for Distributed
 Tools.  This has not been tested at all under Mac OS X and may not compile
 or work at all.  Just use the standard Linux instructions.

0. To be able to start developing code on Mac OS X, you first need to install
   the xcode environment from Apple (if you haven't already done this).
You can get this by going to:
https://developer.apple.com/xcode/   and following the instructions there.


1. Install QT 4.5.2 onto your mac. Go to: http://get.qt.nokia.com/qt/source/
and download: qt-mac-opensource-4.5.2.dmg

Open the file and run installer.

If "qmake" is now accessible from the terminal, you should be ready to go.
It should be in /usr/bin

You will need to do the remaining instructions from the terminal app.

2. Follow the Linux instructions to download and install the buddy BDD
   libraries.  When it comes time to install the libraries, you will likely
need to use: sudo make install

3. Replace the Linux "qmake DESpot.pro" step with: 
   qmake -spec macx-g++  DESpot.pro

4. The rest of the steps should be the same except for how to start DESpot.
   To start DESpot, use: open release/DESpot.app

WARNING: using "open" will fork a new process and any eror messages will not
 show up at the terminal.  If you need  to see these messages for debugging, 
then start DESpot using: release/DESpot.app/Contents/MacOS/DESpot

5.  If you use the finder to copy DESpot.app to the desktop, you can then  
    doubleclick on the icon to start DESpot.

WARNING: when the DESpot help files say to right click to get a context menu, 
hold down "control" then click.

	
+++++++++++++++++++++++++++++++++++++++++++++++++++++++

Windows INSTRUCTIONS

+++++++++++++++++++++++++++++++++++++++++++++++++++++++
++NOTE++ Distributed processing is not supported for Windows builds

Steps to setup Visual Studio environment 

   1. Download the Express version of Visual Studio C++ 2010 Express and install

http://www.microsoft.com/visualstudio/en-us/products/2010-editions/visual-cpp-express

   2. For C++ support, download the windows platform SDK: 

 http://www.microsoft.com/downloads/en/details.aspx?FamilyID=6b6c21d2-2006-4afa-9702-529fa782d63b&displaylang=en 

Though it says Windows 7 it works for Vista and Windows XP Service
Pack 3.  

   3. 1. Download the zip file of the latest version of DESpot
      (i.e. DESpot.1.0.10.zip) and extract it.

   4. Download the latest zip file of the windows version of
      the BuDDy libraries (BuDDy2.4Win.zip).  Extract  the contents
   to the BuDDy subdirectory of your DESpot source code directory.

   If you downloaded your source code to: D:\DESpot.1.0.10,
   you should end up with your Buddy source code in: 
   D:\DESpot.1.0.10\BuDDy\BuDDy2.4Library\

   5. Get Qt 4.5.2 and extract the files.

 http://get.qt.nokia.com/qt/source/qt-win-opensource-src-4.5.2.zip

Open the VS 2010 command window from Tools menu, change to the QT
directory, and type: 

 configure.exe -platform win32-msvc2008 -no-webkit -no-phonon -no-phonon-backend -no-scripttools -no-qt3support -fast

You will be asked which version of QT to use.  You should select only
the opensource version.

then type:  nmake

The above is essentially compiling the QT libs for use with vc++.  It
will likely take quite a while.

   5. Add the  Qt "bin" folder to the windows PATH variable

For current Windows, you can extend PATH using the
Control Panel|System|Advanced|Environment variables menu.

Can also use: right click “My Computer > Properties > Advanced >
Environment Variables”.  

   6. Set the QTDIR environment variable to the root Qt folder  (i.e
      c:\qt\4.5.2-msvc2010 if this is your QT install directory)

Right click “My Computer > Properties > Advanced >
Environment Variables” and add a new variable QTDIR

   7. Open the DESpot.sln file within Visual Studio 

NOTE: You may need to restart VC++ if you already had it open prior to
setting environment vars and compiling Qt 

   8. Build the project from the IDE using "Build\Rebuild Solution"
   menu item.  In the toolbar, you will see a space to select the
   build configuration to use.  Make sure it is set to "release"  and
   not "debug."
   
   Note: If you are getting strange error about MPI at this point, check
   CommonDefinitions.h to see if the line #define __ENABLE_DIST__ is
   uncommented. If it is, comment it out, save, and let Dr. Leduc know
   that the line has  been checked in uncommented.


In the "release" subdirectory of your DESpot source code directory,
you should find a DESpot.exe binary.  Start this to run DESpot.




