Building ruby-opengl

Pre-requisites

General

Linux

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

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

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.

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).

Important note: 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

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