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
To build a Ruby module, run SWIG using the -ruby option :
%swig -ruby example.i
Compiling a dynamic module
Using your module
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