Building ruby-opengl
====================

Pre-requisites
--------------

General
--------------
* C compiler (not needed for binary install on Windows)
* ruby 1.8.5+ or ruby 1.9.0+
* rake
* mkrf 0.2.0+ (0.2.3+ for ruby 1.9)
* rubygems 0.9.1+
* OpenGL headers for OpenGL version 1.1 or later (not needed for binary install on Windows)
* GLUT 3.7+ or API-compatible implementation (freeglut,OpenGLUT)

Linux
--------------
On Ubuntu or Debian systems, aside from Ruby you'll need ruby and
some extra ruby related packages:

* `ruby rdoc ri ruby1.8-dev`

For OpenGL related headers you'll need the following packages:

* `libgl1-mesa-dri libglu1-mesa freeglut3`
* `libgl1-mesa-dev libglu1-mesa-dev freeglut3-dev`

On older Gentoo, Debian and Ubuntu, rubygems 0.9.0 will be installed by default
in the packages.  This version of rubygems is INCOMPATIBLE with ruby-opengl.
You'll need to install rubygems 0.9.1+ from source.

On some distributions you may need 'xorg-dev' developer package.

Mac OS X
--------------
On OS X, you will need to install your own version of Ruby as the
version that ships with OS X has known problems with properly building
ruby-opengl bindings.  You'll also need XCode for gcc and tools.  Macports
or fink should handle this cleanly.

* To compile under Mac OS X you MUST install your own version of Ruby
  as the version included with Tiger (1.8.2) has a broken rbconfig
  and will fail to build the project properly.  Try either [MacPorts][],
  [Fink][], or [building your own from source][].

[Macports]: http://www.macports.org/
[Fink]: http://finkproject.org/
[building your own from source]: http://www.ruby-lang.org/en/downloads/

Windows
--------------
For manual build on Windows you need to have platform SDK and compiler that *must* match the one which was used for compiling ruby binary (for One-click ruby installer it is MSVC 6.0).
You may also need 'glut.h' in SDK include directory, as the One-click ruby
installer is missing it. You can copy the file from glut package at [glut homepage][].
Alternatively, you can install the precompiled binary gem (see bellow).

<b>Important note:</b> If you are using the One-click installer version 1.8.6-25 or earlier,
you must delete or rename files 'opengl.so' and 'glut.so' in
C:/ruby/lib/ruby/site_ruby/1.8/i386-msvcrt

[glut homepage]: http://www.xmission.com/~nate/glut.html

Build and installation
--------------

Installing from rubygems
-------------------

ruby-opengl should support being installed via gems now.  Just
try 'gem install -y ruby-opengl' and it should pull down the gem
and try to build the bindings for you automatically.

For windows there is also pre-built binary windows gem available
(i386-mswin32) which is compatible with the ruby one-click installer and does not need
compiler or other mentioned tools installed.

Manual Build instructions for all platforms (see above for platform-specific notes)
------------------
1. Make sure you have working ruby with rubygems installed
	 and (if needed) appropriate developer packages (ruby-dev,ruby1.8-dev,...).
2. Make sure you have working C compiler
3. Install rake either from package or by running 'gem install rake'
4. Install mkrf (0.2.0+) either from package or by running 'gem install mkrf'
5. Make sure you have working OpenGL installation, this includes libGL,libGLU,
   glut and (if needed) appropriate -dev or -devel packages.
6. Run 'rake' at the top level of the project
7. (OPTIONAL) Run 'rake test' to run unit tests to verify it works properly

Installing manually built extensions
------------------
1. Run 'rake clean' to clean out the project
2. Run 'rake gem' to create source gem from project
3. Run 'gem install pkg/ruby-opengl-(version).gem' to compile and install the gem
4. Done.

Building binary gem (useful only for binary distribution of the project)
------------------
1. Run 'gem install gembuilder' to install the gembuilder package
2. Run 'rake clean' to clean out the project
3. Run 'rake gem' to build source gem
4. Run 'gembuilder pkg/ruby-opengl-(version).gem' to compile the binary gem


Testing
-----------------

To run unit tests:

   $ rake test

Note that the tests have the adverse effect of testing the underlying OpenGL
implementation, so depending on your GL provider,drivers or OS, the tests may
fail, crash, or not run at all, without affecting your ability to use the
bindings.

Running programs and examples
-----------------
To run a sample file, make sure the ruby-opengl gem is installed then:

    $ cd examples
    $ ruby -rubygems plane.rb
