Chapter 2. Installing from Gems
Prev | Part I. The Basics | Next

## Chapter 2. Installing from Gems

## Introduction

Starting with FXRuby version 1.2, FXRuby uses RubyGems as its packaging and distribution method. The code is available both as

- a "source" gem, which contains source code that must be compiled on your computer before it's installed; and,

- a "binary" gem, which contains a precompiled version of the code for a specific operating system (such as Windows).

## Installing from a Source Gem

If you've already downloaded the source gem, you can install it by typing:

    $ sudo gem install fxruby-1.2.2.gem

Note the use of the sudo command to invoke superuser privileges, since you'll typically need superuser privileges to install the library files. By default, the source gem will look for your FOX (and optionally, FXScintilla) installation in a few standard places, such as the `/usr`, `/usr/local` and `/sw` directories. If you've installed those libraries under some other directory (for example, in your home directory) you might need to pass some additional arguments on the command line, e.g.

    $ sudo gem install fxruby-1.2.2.gem --force -- --with-fox-include=/home/lyle/include/fox-1.2 --with-fox-lib=/home/lyle/lib

If you're installing a source gem on a Windows box, you'd instead type something like:

    C:\> gem install fxruby-1.2.2.gem --force -- --with-fox-include=C:\include\fox-1.2 --with-fox-lib=C:\lib

If you're installing a source gem, it can take quite awhile to build FXRuby, so this might be a good time to take a coffee break. You won't see any compiler output appear on the screen while the gem is compiling, but rest assured that the output is being saved into the `gem_make.out` file.

As a quick sanity check, to make sure that all is well, you should probably fire up `irb` and try to require the FXRuby gem once the installation is complete:

    $ irb
    irb(main):001:0> require 'rubygems'
    trues
    irb(main):002:0> require 'fox12'
    true

If the import failed (usually with a message along the lines of "Cannot load library"), first check the "Things That Can Go Wrong" section of this chapter. If that doesn't help, drop me an e-mail or ask around on the Ruby newsgroup or mailing list; it's quite likely that someone else has run into this problem too. Once you do have a working FXRuby installation, you're ready to check out the example programs.

## Installing from a Binary Gem

To install a binary gem for Windows, just type:

    C:\> gem install fxruby-1.2.2-mswin32.gem

As a quick sanity check, to make sure that all is well, you should probably fire up `irb` and try to require the FXRuby gem once the installation is complete:

    C:\> irb
    irb(main):001:0> require 'rubygems'
    true
    irb(main):002:0> require 'fox12'
    true

If the import failed (usually with a message along the lines of "Cannot load library"), first check the "Things That Can Go Wrong" section of this chapter. If that doesn't help, drop me an e-mail or ask around on the Ruby newsgroup or mailing list; it's quite likely that someone else has run into this problem too. Once you do have a working FXRuby installation, you're ready to check out the example programs.

## Things That Can Go Wrong

"Cannot load library"

On Linux and other Unix systems that support shared libraries, FOX is typically installed as a shared library named `libFOX-1.2.so`. After all of the source files for FXRuby are compiled, the last step is to link all of the FXRuby object files together with the FOX library (and possibly other system libraries) to produce a new shared object that Ruby can import as an extension module.

There are a few things that can go wrong when you try to import this extension into Ruby. A common problem is that the operating system cannot locate the FOX shared library (`libFOX-1.2.so`) when it tries to dynamically load the FXRuby extension module; when this happens, the error message will look something like:

    $ irb
    irb(main):001:0> require 'fox'
    LoadError: libFOX-0.99.so.173: cannot open shared object file: No such file or directory - /usr/local/lib/ruby/1.8/i686-linux/fox.so
            from (irb):1:in 'require'
            from (irb):1

Note that the wording of this error message may be slightly different, depending on your operating environment. One workaround for this problem is to modify the `LD_LIBRARY_PATH` environment variable to include the directory where `libFOX-1.2.so` is installed. For example, if `libFOX-1.2.so` is installed in `/usr/local/lib`, try setting:

    $ export LD_LIBRARY_PATH=/usr/local/lib
    $ irb
    irb(main):001:0> require 'fox'

If this works, you can of course permanently add the `LD_LIBRARY_PATH` setting to your login file(s) so that you don't have to remember to type it each time. Another approach that should work for Linux is to modify your `/etc/ld.so.conf` file to include the installation directory (e.g. `/usr/local/lib`). If you'd like to do this instead, you'll need to (as root):

1. Edit your `/etc/ld.so.conf` file and add the directory where `libFOX.so` is installed; and,

2. At the shell prompt, type ldconfig to reload the linker configuration.

Prev | Up | Next
Chapter 1. Building from Source Code | Home | Chapter 3. Hello, World!