SWIG and Ruby
This chapter describes SWIG's support of Ruby.
Note that this chapter is in its early infant stage and only really has some advice for using SWIG and Ruby on Windows.
Preliminaries
SWIG 1.3 is known to work with Ruby 1.6.4 and Ruby 1.6.5, but should work with other versions. Given the choice, you should use the latest version of Ruby. You should also determine if your system supports shared libraries and dynamic loading. SWIG will work with or without dynamic loading, but the compilation process will vary.
Running SWIG
As described in the introduction, a
module is created from an interface file, which contains function
prototypes and variable declarations. For example.c this would
conventionally be called example.i. Often it may be
possible to use the C file itself as if it were a .i file,
as described in the Shortcuts section of the introduction.
To build a Ruby module, run SWIG using the -ruby option :
%swig -ruby example.i
It should be noted that if the .c file is used instead of the
.i file, then the -module Example must be used on the
command line:
%swig -ruby -module Example example.i
Alternatively, a real .i file may be created containing
%module Example
Swig will create example_wrap.c which together with
example.c can then be compiled and linked to produce
example.so. This library can then be handled by Ruby's
require statement.
If many .c files are to be used together in the same module, then
several .i files may be tied together by creating one overall
.i file
%module MyModule
%include somefuncs.i
%include someotherfuncs.i
Compiling a dynamic module
Conventionally with SWIG on Unix the compilation of examples
is done using the file
Example/Makefile. This
makefile performs a manual module compilation which is platform
specific. Typically, the steps look like this (Linux):
% swig -ruby example.i
% gcc -fpic -c example_wrap.c -I/usr/local/lib/ruby/1.4/i686-linux
% gcc -shared example_wrap.o $(OBJS) -o example.so
However the politically "correct" way to compile a Ruby extension is to
follow the steps described README.EXT in Ruby distribution:
- Create a file called extconf.rb that looks like the
following:>
require 'mkmf'
create_makefile('interface')
- Type the following to build the extension:
% ruby extconf.rb
% make
% make install
Because the compilation step is performed here, there should be no need
to invoke the SWIG Examples/Makefile
Using your module
The library produced by SWIG contains a module in the Ruby sense. Ic
may be accessed by having statements such as
require "Example"
Example.my_function(this, that, other)
in the code.
Building Ruby Extensions under Windows 95/NT
Building a SWIG extension to Ruby under Windows 95/NT is roughly similar to the process used with Unix. Normally, you will want to produce a DLL that can be loaded into the Ruby interpreter. This section covers the process of using SWIG with Microsoft Visual C++ 6 although the procedure may be similar with other compilers. In order to build extensions, you will need to download the source distribution to the Ruby package as you will need the Ruby header files.
Running SWIG from Developer Studio
If you are developing your application within Microsoft developer studio, SWIG can be invoked as a custom build option. The process roughly follows these steps :
- Open up a new workspace and use the AppWizard to select a DLL project.
- Add both the SWIG interface file (the .i file), any supporting C files, and the name of the wrapper file that will be created by SWIG (ie. example_wrap.c). Note : If using C++, choose a different suffix for the wrapper file such as example_wrap.cxx. Don't worry if the wrapper file doesn't exist yet--Developer Studio will keep a reference to it around.
- Select the SWIG interface file and go to the settings menu. Under settings, select the "Custom Build" option.
- Enter "SWIG" in the description field.
- Enter "swig -ruby -o $(ProjDir)\$(InputName)_wrap.c $(InputPath)" in the "Build command(s) field". You may have to include the path to swig.exe.
- Enter "$(ProjDir)\$(InputName)_wrap.c" in the "Output files(s) field".
- Next, select the settings for the entire project and go to the C/C++ tab and select the Preprocessor category. Add NT=1 to the Preprocessor definitions. This must be set else you will get compilation errors. Also add IMPORT to the preprocessor definitions, else you may get runtime errors. Also add the include directories for your Ruby installation under "Additional include directories".
- Next, select the settings for the entire project and go to the Link tab and select the General category. Set the name of the output file to match the name of your Ruby module (ie. example.dll). Next add the Ruby library file to your link libraries under Object/Library modules. For example "mswin32-ruby16.lib. You also need to add the path to the library under the Input tab - Additional library path.
- Finally still under the Link tab, add the dll entry point in the Project Options: Use "/EXPORT:Init_example" for when you have set the swig module name to 'example'. In general use "/EXPORT:Init_", where is the swig module name (specified using %module in your interface file).
- Build your project.
Now, assuming all went well, SWIG will be automatically invoked when you build your project. Any changes made to the interface file will result in SWIG being automatically invoked to produce a new version of the wrapper file. To run your new Ruby extension, simply run Ruby and use the require command as normal. For example if you have this ruby file run.rb:
# file: run.rb
require 'example'
# Call a c function
print "Foo = ", Example.Foo, "\n"
Ensure the dll just built is in your path or current directory, then run the Ruby script from the DOS/Command prompt:
c:\swigtest>ruby run.rb
Foo = 3.0