build.xml

<?xml version="1.0" encoding="UTF-8"?>
<chapter id="build">
  <title>Building from Source Code</title>

  <para>This chapter provides instructions for building and installing FXRuby
  directly from source, and not using some more direct means (such as
  installing a gem, or via some package manager).</para>

  <itemizedlist>
    <listitem>
      <para>If you're planning to use FXRuby on Windows, with the standard
      <ulink url="http://rubyinstaller.rubyforge.org">Ruby Installer for
      Windows</ulink>, you may wish to just download the pre-compiled binaries
      from the <ulink url="http://rubyforge.org/projects/fxruby">RubyForge
      project page</ulink> for FXRuby.</para>
    </listitem>

    <listitem>
      <para>If you're already using the <ulink
      url="http://www.macports.org/">MacPorts</ulink> version of ruby, you may
      wish to just install the <filename>rb-fxruby</filename> port.</para>
    </listitem>
  </itemizedlist>

  <simplesect>
    <title>Building From Source on Unix/Linux</title>

    <para>These instructions assume that you've already downloaded, compiled
    and installed FOX. Next, you'll need to download the FXRuby source code
    tarball and unpack it by typing:</para>

    <screen>$ <command>tar xzf FXRuby-1.6.19.tar.gz</command></screen>

    <para>This will create a new directory called <filename
    class="directory">FXRuby-1.6.19</filename>. Change to the top-level
    directory and configure the build by typing:</para>

    <screen>$ <command>ruby install.rb config</command></screen>

    <para>By default, the <filename>install.rb</filename> script will look for
    the FOX include files and library in the standard <filename
    class="directory">/usr/local/include/fox-1.6</filename> and <filename
    class="directory">/usr/local/lib</filename> directories, respectively. You
    can override these locations by passing a few additional arguments to
    <filename>install.rb</filename> during this step, e.g.</para>

    <screen>$ <command>ruby install.rb config -- \
    --with-fox-include=/home/lyle/fox-1.6.36/include \
    --with-fox-lib=/home/lyle/fox-1.6.36/src/.libs</command></screen>

    <para>Once the build has been configured, you can start the build by
    typing:</para>

    <screen>$ <command>ruby install.rb setup</command></screen>

    <para>It will take quite awhile to build FXRuby, even on a fast machine,
    so this might be a good time to take a coffee break. If you run into
    problems during the compilation, please check the <link
    linkend="tragedies">list of things that can go wrong</link> for
    workarounds for those problems.</para>

    <para>Once it's finished compiling, install FXRuby by typing:</para>

    <screen>$ <command>ruby install.rb install</command></screen>

    <para>As a quick sanity check, to make sure that all is well, you should
    probably fire up <filename>irb</filename> and try to import FXRuby:</para>

    <screen>$ <command>irb</command>
irb(main):001:0&gt; <userinput>require 'fox16'</userinput>
true
irb(main):002:0&gt;</screen>

    <para>If the import failed (usually with a message along the lines of
    "Cannot load library"), check the <link linkend="tragedies">list of things
    that can go wrong</link> for known problems. If that still doesn't solve
    your problem, 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.</para>
  </simplesect>

  <simplesect>
    <title>Building From Source on Windows (Using Visual C++)</title>

    <para>This section describes how to compile FXRuby using Microsoft Visual
    C++, for use with a Ruby that was also compiled using Visual C++.</para>

    <para>This discussion assumes that you've built Ruby using the
    instructions and build files distributed with the standard Ruby source
    code. To review, you should have started by unpacking the source code
    tarball, changing into the top-level source code directory (e.g. <filename
    class="directory">C:\ruby-1.8.6</filename>) and then typing:</para>

    <screen>C:\ruby-1.8.6&gt;<command>win32\configure</command>
type 'nmake' to make ruby for mswin32.
C:\ruby-1.8.6&gt;<command>nmake</command></screen>

    <para>After the compilation finished, you installed Ruby somewhere by
    typing, e.g.,</para>

    <screen>C:\ruby-1.8.6&gt;<command>nmake DESTDIR=C:\ruby install</command></screen>

    <para>Similarly, I'm assuming that you built the FOX library using the
    Developer Studio project files distributed with the standard FOX source
    code distribution.</para>

    <para>Now you can configure the FXRuby build by typing:</para>

    <screen>C:\FXRuby-1.6.19&gt;<command>ruby install.rb config --make-prog=nmake -- \
    --with-fox-include=C:\fox-1.6.36\include \
    --with-fox-lib=C:\fox-1.6.36\lib</command></screen>

    <para>Once the build has been configured, you can start the build by
    typing:</para>

    <screen>C:\FXRuby-1.6.19&gt; <command>ruby install.rb setup</command></screen>

    <para>It will take quite awhile to build FXRuby, even on a fast machine,
    so this might be a good time to take a coffee break. Because Visual C++ is
    such a strict compiler (usually a good thing), you will probably run into
    a few problems with non-ANSI declarations in the Ruby header files. If you
    do run into problems during the compilation, just check the next section
    for a list of things that could go wrong, and workarounds for those
    problems. None of them are showstoppers and none require you to restart
    the compile from scratch (just type <command>ruby install.rb
    setup</command> to pick up where you left off).</para>

    <para>Once it's finished compiling, install FXRuby by typing:</para>

    <screen>C:\FXRuby-1.6.19&gt; <command>ruby install.rb install</command></screen>

    <para>As a quick sanity check, to make sure that all is well, you should
    probably fire up <filename>irb</filename> and try to import FXRuby:</para>

    <screen>C:\FXRuby-1.6.19&gt; <command>irb</command>
irb(main):001:0&gt; <userinput>require 'fox16'</userinput>
true
irb(main):002:0&gt;</screen>

    <para>If the import failed (usually with a message along the lines of
    "Cannot load library"), check the list of things that can go wrong for
    known problems. If that still doesn't solve your problem, 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.</para>
  </simplesect>

  <simplesect id="tragedies">
    <title>Things That Can Go Wrong</title>

    <para><emphasis>"Too many arguments to function..."</emphasis></para>

    <para>The include files for Ruby versions 1.6.7 and earlier still have
    several function prototypes in the older "K &amp; R" C style, where the
    function's argument list is not included; for example, the function
    <function>rb_thread_wait_for()</function> takes a single argument of type
    <type>struct timeval</type>, but its prototype in
    <filename>intern.h</filename> is:</para>

    <programlisting format="linespecific">void rb_thread_wait_for();</programlisting>

    <para>Because FXRuby is written in C++, and C++ requires strict ANSI
    C-style function prototypes, code that attempts to call one of these
    functions will fail to compile under some compilers. For example, the
    error message from gcc will look something like this:</para>

    <screen>FXRbApp.cpp: In method `long int FXRbApp::onChoreThreads (FXObject *, unsigned int, void *)':
/usr/local/lib/ruby/1.8/i686-linux/intern.h:172: too many arguments to function `void rb_thread_wait_for ()'
FXRbApp.cpp:100: at this point in file
make: *** [FXRbApp.o] Error 1</screen>

    <para>while the error message from Microsoft's Visual C++ compiler looks
    something like this:</para>

    <screen>FXRbApp.cpp(109): error C2660: 'rb_thread_wait_for' : function does not take 1 parameters
NMAKE : fatal error U1077: 'cl' : return code '0x2'
Stop.</screen>

    <para>This problem with the Ruby header files has been corrected for Ruby
    versions 1.6.8 (and later), but if you're building for an older version of
    Ruby you can do one of two things to work around the problem:</para>

    <itemizedlist mark="bullet">
      <listitem>
        <para>If you're using gcc version 2.95 or earlier, try modifying the
        compiler flags (<constant>CFLAGS</constant>) in the FXRuby
        <filename>Makefile</filename> to include the
        <option>-fno-strict-prototype</option> option; this should instruct
        the compiler to allow these kinds of discrepancies. Unfortunately,
        this flag is not supported in more recent versions of gcc.</para>
      </listitem>

      <listitem>
        <para>A more direct approach is to just fix the offending declarations
        in the Ruby include file(s), i.e. change the declaration for
        <function>rb_thread_wait_for()</function> in
        <filename>intern.h</filename> to read:</para>

        <programlisting format="linespecific">void rb_thread_wait_for(struct timeval);</programlisting>

        <para>and change the declaration for <function>rb_gc_mark()</function>
        in <filename>intern.h</filename> to read:</para>

        <programlisting format="linespecific">void rb_gc_mark(VALUE);</programlisting>
      </listitem>
    </itemizedlist>

    <para><emphasis>"Virtual Memory Exhausted"</emphasis></para>

    <para>For FXRuby releases earlier than version 0.99.173 it was common for
    the compiler to run out of memory trying to compile
    <filename>core_wrap.cpp</filename>, with an error message like:</para>

    <screen>core_wrap.cpp: In function 'void Init_core()':
core_wrap.cpp:108596: virtual memory exhausted</screen>

    <para>This failure was due to the use of optimizations by the compiler;
    the FXRuby source code makes heavy use of C++ templates and some versions
    of gcc require a lot of memory to process these. Starting with FXRuby
    version 0.99.173, the <filename>extconf.rb</filename> script
    <emphasis>should</emphasis> disable compiler optimizations when it
    generates the FXRuby <filename>Makefile</filename>. If you suspect that
    it's not disabling optimizations (or can see this by watching the compile
    command lines), try modifying the compiler flags
    (<constant>CFLAGS</constant>) in the <filename>Makefile</filename> by hand
    to do so.</para>

    <para><emphasis>"Cannot load library"</emphasis></para>

    <para>On Linux and other Unix systems that support shared libraries, FOX
    is typically installed as a shared library named
    <filename>libFOX-1.6.so</filename>. 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 library, named <filename>fox16.so</filename>, that
    Ruby can import as an extension module.</para>

    <para>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 (<filename>libFOX-1.6.so</filename>) when it
    tries to dynamically load the FXRuby extension module; when this happens,
    the error message will look something like:</para>

    <screen>$ <command>irb</command>
irb(main):001:0&gt; <userinput>require 'fox16'</userinput>
LoadError: libFOX-1.6.so: cannot open shared object file: No such file or directory - /usr/local/lib/ruby/1.8/i686-linux/fox16.so
        from (irb):1:in 'require'
        from (irb):1
    </screen>

    <para>One workaround for this problem is to modify the
    <constant>LD_LIBRARY_PATH</constant> environment variable to include the
    directory where <filename>libFOX-1.6.so</filename> is installed. For
    example, if <filename>libFOX-1.6.so</filename> is installed in <filename
    class="directory">/usr/local/lib</filename>, try setting:</para>

    <screen>$ <command>export LD_LIBRARY_PATH=/usr/local/lib</command>
$ <command>irb</command>
irb(main):001:0&gt; <userinput>require 'fox16'</userinput>
</screen>

    <para>If this works, you can of course permanently add the
    <constant>LD_LIBRARY_PATH</constant> 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
    <filename>/etc/ld.so.conf</filename> file to include the installation
    directory (e.g. <filename>/usr/local/lib</filename>). If you'd like to do
    this instead, you'll need to (as root):</para>

    <orderedlist numeration="arabic" spacing="compact">
      <listitem>
        <para>Edit your <filename>/etc/ld.so.conf</filename> file and add the
        directory where <filename>libFOX-1.6.so</filename> is installed;
        and,</para>
      </listitem>

      <listitem>
        <para>At the shell prompt, type <command>ldconfig</command> to reload
        the linker configuration.</para>
      </listitem>
    </orderedlist>

    <para><emphasis>"Undefined symbol..."</emphasis></para>

    <para>Another problem that has been reported by users of both Debian
    GNU/Linux and NetBSD 1.5 is an error message along the lines of:</para>

    <screen>/usr/lib/libstdc++.so.2: Undefined symbol "__vt_9exception"...</screen>

    <para>The fix for this problem is reported to be to modify the FXRuby
    <filename>Makefile</filename> and add <option>-lgcc</option> to the
    <constant>LIBS</constant> line.</para>
  </simplesect>
</chapter>