src/README

   1 MIT PROTO INSTALLATION GUIDE
   2 (Last Revision: $Date$)
   3
   4 This is a guide to getting the Proto compiler, kernel, and simulator
   5 running on your system.  All other documentation is located in the
   6 directory ../man/
   7
   8
   9 0. LICENSING
  10
  11 MIT Proto is Copyright (C) 2005-2008, Jonathan Bachrach, Jacob Beal,
  12 and contributors listed in the AUTHORS file in the MIT Proto
  13 distribution's top directory.
  14
  15 MIT Proto is distributed under the terms of the GNU General Public
  16 License, with a linking exception, as described in the file LICENSE in
  17 the MIT Proto distribution's top directory.
  18
  19
  20
  21 1. DEPENDENCIES
  22
  23 Proto depends on the following applications and libraries:
  24 * GNU C/C++ (v. 4.0 or later)
  25 * GNU make      (usually bundled with GNU C/C++)
  26 * flex          (usually bundled with GNU C/C++)
  27 * OpenGL (and GLUT)
  28 * X Windows
  29 * Open Dynamics Engine (ODE) v0.8  [optional]
  30
  31 If you have all of these installed, you should just be able to run
  32 'make' in this directory and have the whole thing build correctly.
  33
  34   If you are missing OpenGL, run 'make NO_GL=true'
  35   If you are missing ODE, the makefile should automatically detect
  36     this fact and exclude ODE.  You can also run 'make NO_ODE=true'
  37
  38 Furthermore, each platform has its own additional requirements. See
  39 README under particular platform directories
  40 (e.g. platforms/protobo/README)
  41
  42 The Prototest regression testing package requires Python 2.5
  43
  44 The standalone compiler application (p2b) depends only on GNU C/C++
  45   and make, and can be built with 'make compiler'
  46
  47
  48 2. INSTALLATION
  49
  50 If you've got all the dependencies taken care of, you should
  51 be able to build MIT Proto by typing 'make' in this directory.
  52 This will produce two applications:
  53
  54 * proto: Proto simulator (incorporating compiler)
  55 * p2b:   Proto standalone compiler
  56
  57 You will generally want to invoke these from the directory you're
  58 writing Proto code in, so add the src/ directory to your path.  For
  59 example, if your shell is tcsh, you would do this by opening the file
  60 '~/.tcshrc' and adding the line:
  61
  62   setenv PATH "${PATH}:[DIRECTORY]/proto/src"
  63
  64 replacing [DIRECTORY] with the directory where you put your copy
  65 of Proto.  If your shell is bash, you would instead open the file
  66 '~/.bashrc' and add the line:
  67
  68   export PATH=$PATH:[DIRECTORY]/proto/src
  69
  70 Other shells have other ways of modifying the path, easily found on
  71 the web.
  72
  73
  74 3. SYSTEMS
  75
  76 Proto is intended to work on Linux, BSD, MacOS X, and Windows.
  77
  78 Proto has been tested on the following platforms:
  79 * Debian Lenny, CSAIL Debian, Ubuntu Gutsy & Hardy, Linux Mint Darnya
  80 * Fedora Sulphur 9, CentOS 5
  81 * PC-BSD 1.5.1 [currently not working]
  82 * Mac OS X: 10.4, 10.5
  83 * Windows: XP (with Cygwin), Vista (with Cygwin)
  84
  85 If you have the required dependencies, we expect proto to work without
  86 any problems.
  87
  88
  89 4. PLATFORM-SPECIFIC INSTRUCTIONS:
  90
  91 A. Linux
  92
  93 Installing the Required Packages:
  94 * Debian/Ubuntu/derivatives: use apt-get to install make, gcc, g++,
  95   libode0-dev, libglut3-dev
  96 * RedHat/CentOS/Fedora/derivatives: use yum to install make, gcc,
  97   gcc-c++, freeglut-devel.i386, ode.i386.  You might have to compile
  98   ode yourself on CentOS.
  99
 100 Other Notes:
 101 * If you have ATI/NVIDIA graphics cards, using the "Restricted
 102   Drivers" greatly increases performance.
 103 * DEBIAN: When using nvidia drivers in Debian, you may need to install
 104   nvidia-glx-dev to get the OpenGL rendering to work correctly. If
 105   your make complains during linking that it cannot find "pthread"
 106   routines, this is likely the problem.
 107 * DEBIAN: Debian may not, by default, search for libraries in the
 108   directory where ODE is likely to have installed itself.  By default,
 109   ODE installs in /usr/local/lib.  If that is not part of the library
 110   path, add it to /etc/ld.so.conf and run ldconfig
 111
 112 B. Windows
 113 * Proto expects the its GNU and X to be provided by Cygwin.
 114 * Cygwin doesn't install gcc, g++, make, or OpenGL by default.
 115 * USING ODE: The easiest way is to get use the "Autotools" method with
 116   Cygwin (as described in ODE's install notes). You will need to tell
 117   Cygwin to install "libtool" to install ode this way.
 118
 119 C. MacOS X
 120 * If OpenGL and GNU tools aren't already installed, install the
 121   following Xcode packages: DevSDK.pkg and OpenGLSDK.pkg
 122
 123 D. BSD
 124 * You need GNU Make to compile proto.
 125 * Make sure that your version of GCC is 4.0 or later. Either alias the
 126   new version of GCC to "gcc", or make changes to the Makefile to
 127   ensure that the new version is used. (Changing all instances of
 128   "gcc" to "gcc4_3" should suffice).
 129 * If your /proc filesystem is not mounted, Proto cannot determine
 130   where it is running, and will be unable to load.  If this happens
 131   to you, log in as root and run 'mount -t procfs proc /proc'
 132
 133
 134 5. OTHER KNOWN ISSUES
 135
 136 * Proto should really install itself into a normal location, rather
 137   than forcing the user to adjust their path.