R2CORBA Programming : Installing R2CORBA for MRI

Introduction

R2CORBA is the reference implementation of the Ruby CORBA Language Mapping (RCLM) created by Remedy IT. Ruby is a popular scripting language created by Yukihiro Matsumoto (a.k.a. matz) featuring a very dynamic form of Object Orientation. See here for more information.
There are multiple implementations of Ruby interpreters available for various platforms (C-based, Java, .NET etc.).

R2CORBA does not provide a native Ruby ORB implementation but rather reuses existing ORB implementations on top of which it implements the Ruby CORBA Language Mapping.
R2CORBA has been implemented for the two most used implementations of Ruby interpreters:

• for MRI (or the original C-Ruby; MRI stands for Matz's Ruby Interpreter ) including C extension libraries interfacing to TAO
• for JRuby (Java based interpreter) interfacing to JacORB

In this article I will describe how to build and install R2CORBA for MRI from source.

Installing R2CORBA

Getting R2CORBA

To install R2CORBA you first have to get the software somewhere. The R2CORBA project at the Remedy IT OSPortal site always provides the latest (and previous) source packages and a number of prebuilt packages in various archive formats for download. I recommend downloading a package from the latest version. When you have downloaded one of these packages unpack it into a location of your choice on your system. Unpacking creates an R2CORBA subdirectory at the location where you unpacked. Like f.i.:

$ cd <any location>
$ tar -xzf <download location>/Ruby2CORBA-1.0.0.tar.gz
$ cd R2CORBA

Besides these packages Remedy IT also provides RPM packages for a number of major Linux distributions through the OpenSuSE Build Service (OBS). To download these navigate to the OpenSuSE software site, enter 'R2CORBA' in the search field, select your Linux distribution of choice and press 'Search'. Currently RPM packages are available for the following Linux distributions:

• OpenSuSE
• CentOS_5
• RHEL_5
• Fedora
• Mandriva
• Novell SLE/SLES

The RPM packages are exclusively available for the MRI version of R2CORBA and depend on ACE+TAO RPM packages which are also made available through the OBS service by Remedy IT. Furthermore, these packages are source distribution only and require the availability of a C/C++ compiler and some tools to install. These dependencies are configured in the packages and your package manager should be able to automatically resolve them.

When installing RPM packages the package manager will take of compiling and installing the resulting artifacts. After successful installation of an RPM package you should have a working R2CORBA installation and you can skip the rest of this chapter.

In the rest of this article I will describe the process of building and installing R2CORBA from source.
Check the included documentation and/or the wiki of the Remedy IT OSPortal project for R2CORBA for more information on installing a prebuilt package.

Building R2CORBA

In case you want to build the JRuby version of R2CORBA skip to the Building JRuby R2CORBA paragraph.

In case you need or want to build R2CORBA for MRI/TAO from source you will need:

• a supported C/C++ compiler (Windows:Ming32 1.0+; Linux and Mac OSX:GCC 3.2+)
• a Perl interpreter (needed for makefile generation with the TAO MPC tool)
• some other tools depending on your platform (see below)

In all case make sure to carefully read the INSTALL file to get the very latest information. The INSTALL file will be unpacked in the root of the R2CORBA directory.
Move to the root of the R2CORBA to make it the current directory from where to execute any of the commands described further on.

R2CORBA provides the setup.rb script to help with configuring, building, testing and installing. Calling the script with the argument --help prints an overview of the commands and options it supports.

Building the easy way (with ACE+TAO)

Most users will simply use the setup.rb provided build method to build both the R2CORBA MRI extension as well as the required ACE+TAO libraries using the default setup. In this case you will need to download an ACE+TAO source distribution and unpack it in the default location. I recommend to download the latest release from the project's download site. Be sure to download a Sources only ACE+TAO package. When downloaded unpack under the ACE sub directory as follows (in the R2CORBA root):

$ mkdir ACE
$ cd ACE
$ tar -xzf <download location>/ACE+TAO-src-6.0.1.tar.gz
$ cd ..

After succesfully unpacking the ACE+TAO source you can configure the build as follows:

$ ruby setup.rb config

This step creates the required configuration files and make files necessary for the following step. When this step has succeeded you can build the ACE+TAO libraries and the R2CORBA MRI extensions as follows:

$ ruby setup.rb setup

This step first builds the ACE+TAO libraries, then builds the R2CORBA MRI extensions and finally compiles a number of core IDL files. After this step has successfully finished you are ready to test if everything works as expected. To validate an R2CORBA build (before installation) the package includes a number of regression tests under the test sub directory. These regression tests each test a certain aspect of the R2CORBA functionality. You can execute the tests as follows:

$ ruby setup.rb test

The last lines of the output should tell you if the tests performed successfully or if any failures were detected like:

...
Finished in 19.914808 seconds.

26 tests, 0 assertions, 0 failures, 0 errors, 0 skips
...

If you are satisfied with the results of the test you can install R2CORBA as an integrated part of your Ruby installation as follows (be aware that on Linux and Mac OSX special requirements may apply for installing; see below):

$ ruby setup.rb install

Building the easy way (without ACE+TAO)

When building R2CORBA using a pre-installed version of ACE+TAO (and MPC!) the process is almost the same (be sure to read the INSTALL file regarding the information concerning the minimum required ACE+TAO version).
Obviously there is no need to download and unpack an ACE+TAO source distribution, so that step can be skipped.

You do have to make sure that the ACE+TAO libraries and include files are in a place where the compiler can find them when compiling the R2CORBA MRI extension and from where the extension can load them when running R2CORBA code. When you have installed ACE+TAO in the default location for most systems (Windows is an exception here; see below) this should not be a problem but when you have installed in a non-default location you may have to set some additional environment variables and/or search paths. Also, the setup.rb script needs to be able to find the ACE mwc.pl script through the system default search path. The configuration step is a little different from configuring with ACE+TAO. Configure the build as follows:

$ ruby setup.rb config --without-tao

This instructs setup.rb not to build the ACE+TAO libraries but rather just use existing ACE+TAO libraries on the system. The remainder of the build and installation process is identical to building with ACE+TAO.

Customizing build options

Running the setup.rb script with the --help argument like

$ ruby setup.rb --help

will print information regarding the available commands and configuration options. I will not discuss all options here but merely the most often used ones:

Configuration options

• The --prefix option determines the base directory for installing R2CORBA files. Normally you do not change this as the script automatically sets this to the correct location according to the installation of the Ruby version you are using.
• The --without-tao option determines if you will be building the required TAO libraries using the same setup.rb driven process as for building the R2CORBA MRI extension itself (do not specify the --without-tao option with the config command) or if you will be reusing a previously built and installed TAO version (do specify the --without-tao option with the config command).
• The --aceroot option can be used to specify the root path of the source distribution of ACE+TAO. You only need this if your source distribution of ACE+TAO is installed anywhere else than the default location; under the ACE sub directory of the R2CORBA directory. Setting this option will automatically set the --taoroot and --mpcroot options as dependents of the --aceroot setting (/TAO and /MPC). These settings can be overruled by adding the other two options separately as well.
• The --with-debug option can be used to specify that the R2CORBA extensions (and the TAO libraries if building them too) are to be built with debugger information (by default no debugger information is included).

Installation option

• The --no-harm option can be used with the install command to test installation. When used the setup.rb will only print what it would do when installing but not actually perform the install action.

Building on Linux

Installation on Linux will often require root access rights to be able to install in system default locations. In this case acquire the appropriate password for your system and execute the install command as follows:

$ sudo ruby setup.rb install 

Building on Windows

For generating make files using the MPC tool an installed Perl is required. For Windows I recommend ActiveState Perl.

To be able to run the regression tests on Windows the Ruby windows-pr gem (and dependencies) needs to be installed. Download and install by executing the command

C:\...> gem install windows-pr

Version 6.5 or higher is required.

The Windows MinGW32 build of R2CORBA requires the following runtime libraries to be installed:

• LIBGGC_S_DW2-1.DLL
• LIBSTDC++-6.DLL

The setup.rb script's install command will install these files in the same location as the ACE+TAO libraries. If you want to create a distribution package for (an) R2CORBA (base application) you may need to distribute these files with it (like f.i. the R2CORBA MinGW prebuilt package). If so, be aware that these files are part of the GNU GCC package and are licensed under GPL.

Windows does not know system default locations for include files and (import) libraries so when building R2CORBA for a pre-installed version of ACE+TAO (uncommon on Windows to say the least) you will need to specify the location to the setup.rb script. This can be done using either the --aceroot (and optionally --taoroot and --mpcroot) option or by setting the ACE_ROOT (and optionally TAO_ROOT and MPC_ROOT) environment variable.
The setup.rb script will expect to find libraries, include files and mwc.pl script in standard locations under the respective ACE,TAO,MPC root locations.
Be aware that this is not a well tested setup variant.

Building on Mac OSX

For generating make files using the MPC tool an installed Perl is required. If your Mac OSX system does not have a version installed I recommend getting it from MacPorts.org. To correctly set up library dependencies on Mac OSX the latest release of the Xcode Tools (developer.apple.com) is required. Specifically the INSTALL_NAME_TOOL is required.

Installation on Mac OSX will often require root access rights to be able to install in system default locations. In this case acquire the appropriate password for your system and execute the install command as follows:

$ sudo ruby setup.rb install 

Finally

When you have successfully installed R2CORBA you are ready to start implementing your very first R2CORBA program.