Installing R2CORBA

Getting R2CORBA

To install R2CORBA you first have to get the software somewhere.

As of version 1.4.1 the distribution packages as well as the installation and build procedures have changed. You can find the 'old’ instructions for previous versions here. Distribution of RPM packages through OBS has been discontinued.

R2CORBA is currently distributed as a Ruby Gem through the Rubygems.org repository as well as source packages downloadable here. Both distribution packages do not include the RIDL compiler frontend code anymore as this has been split off as a separate component/product being used by multiple IDL compiler projects. RIDL is distributed as a Ruby Gem (see also RIDL).
Alternatively you can also clone the R2CORBA code repository as described here.

Installing R2CORBA Gem

You can download and install R2CORBA as a Ruby Gem from the common Rubygems.org repository by executing the following command:

$ gem install r2corba

Installing R2CORBA this way will automatically trigger installation of the RIDL Gem if it has not been installed before (you could also explicitly install the RIDL Gem beforehand by executing gem install ridl).

The R2CORBA Gem provides multiplatform support through binary versions for the supported Windows MRI platforms (32/64bit, MRI 1.8.7, 1.9.3, 2.0.0) as well as the JRuby platform and a source-only version ("Ruby" platform) for the Linux MRI platforms. In all cases the Gem will automatically install a matching ORB.

For the JRuby platform the Gem installs the required JacORB binaries, for the Windows MRI platforms prebuilt ACE/TAO binaries matching the platform are installed and for the source-only version a matching TAO ORB will be automatically built from automatically downloaded sources (depending on your PC this can take more than 10 minutes; be patient).

The installed ORB binaries are installed locally with respect to the installed R2CORBA Gem (whether the Gem is system - or user installed) and should in no way conflict with any system installed ORB binaries.

If you have successfully installed the R2CORBA Gem you can skip to the Your very first R2CORBA program paragraph.

RVM and R2CORBA Gem

Installing the R2CORBA Gem requires Rake for configuring (and possibly building) the extension and therefor lists the Rake Gem as a dependency.
On Linux when installing in a user environment which uses the Ruby Version Manager (RVM) in combination with RVM 'gemsets’ this may cause problems since in the case of global gemsets for a certain Ruby version the extended Gem search path will not be properly propagated to the child processes running the Rake commands possibly resulting in installation failures because of not being able to find the required Rake Gem if this is installed in a global gemset.

There are three possible ways to work around this problem:
  1. install the R2CORBA Gem in the global gemset where the Rake Gem is installed
  2. explicitly install the Rake Gem in the gemset where R2CORBA is to be installed before installing R2CORBA (after having installed R2CORBA the Rake Gem could be removed again)
  3. use the --ignore-gemsets option of RVM to (temporarily) ignore any global gemsets before installing R2CORBA (after having installed R2CORBA the --ignore-gemsets option could be reset again and a possibly implicitly installed, duplicate, Rake Gem removed again)

Testing R2CORBA Gem

The R2CORBA Gem installs a special tool script which can be used to run the included regression tests: r2corba.

Executing r2corba --help will provide information about the options for this tool script.

Executing r2corba test will run the full suite of included regression tests.

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

...
Finished tests in 31.667355s, 1.0421 tests/s, 0.0000 assertions/s.
33 tests, 0 assertions, 0 failures, 0 errors, 0 skips
...

Building R2CORBA

In case you downloaded an R2CORBA source package here (or cloned the R2CORBA Git repository) and want to install for a Ruby MRI platform you need to explicitly build and install R2CORBA as described below in the Building from source paragraph.

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

Alternatively you could also install the source-only Gem ("Ruby" platform) and customize the automatic build process by providing specific build options to the gem install command. This is described in the Custom Gem installation paragraph.

IMPORTANT: As described above RIDL is not included in any R2CORBA distribution packages anymore. The R2CORBA Gem lists the RIDL Gem as a dependency and will therefor automatically install the RIDL Gem as well. When building from a source package you will have to install RIDL yourself.
The easiest way to do this is to install the RIDL Gem (see RIDL).
Alternatively you could grab a copy of the RIDL code from the Git repository and clone that into an ridl subdirectory of the R2CORBA directory (see here for an example).

Building from source

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: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 (source: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 Rake based command scripts to help with configuring, building, testing and installing. Running rake -T will show all available commands. See here for a more detailed description of the R2CORBA Rake commands.

Building the easy way (with ACE+TAO)

Most users building R2CORBA from source will simply use the R2CORBA, through Rake commands, 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. We 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.2.0.tar.gz
$ cd ..

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

$ rake configure

This step configures the R2CORBA build environment for the build step.
When this step has succeeded you can build the ACE+TAO libraries and the R2CORBA MRI extensions as follows:

$ rake build

This step first builds the ACE+TAO libraries, then builds the R2CORBA MRI extensions and finally compiles a number of core IDL files.
When 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:

$ rake test

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

...
Finished tests in 31.667355s, 1.0421 tests/s, 0.0000 assertions/s.
33 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 special requirements may apply for installing; see below):

$ rake install

Unlike R2CORBA Gem installations an R2CORBA installation installed through the rake install command will not include the suite of regression tests.

You can uninstall an R2CORBA version installed through rake install using the following command

$ rake uninstall

under the condition that the installed version is identical to the version in the folder where you are calling rake uninstall from (this is so because the uninstall command needs to determin from the build directory what to actually uninstall).

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 (source:INSTALL) 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 where the extension can load them from 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 Rake commands need to be able to find the MPC 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:

$ rake configure -- --without-tao

This instructs rake build 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 rake with arguments like

$ rake help

and

$ rake configure -- --help

will print information regarding the available commands and configuration options (see also here). We 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. Can also be supplied to the rake install and rake uninstall commands.
    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 (<aceroot>/TAO and <aceroot>/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=1 option can be used with the rake install and rake uninstall commands to test (un)installation. When used the commands will only print what would be done when (un)installing but not actually perform any actions.

Building on Linux

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

$ sudo rake install 

Building on Windows

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

Be sure to check out the latest information in the INSTALL file (source:INSTALL) for the additional requirements for running and testing R2CORBA on Windows.

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 rake configure command. 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 configure command 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 JRuby R2CORBA

Since this variant of R2CORBA uses the Java based, platform independent, JacORB CORBA ORB implementation there is no need to build JacORB from sources ourselves for any platform we are using to install R2CORBA on.
For this reason the rake configure command does not provide support for building JacORB from source but rather relies on the availability of a binary JacORB distribution. If the user has a specific need requiring him/her to build JacORB from source we assume the user is also are well aware of how such a thing must be accomplished and we refer to their own expertise as well as the JacORB website for details.

To install R2CORBA for JRuby you will need at least:
  • JRuby (obviously) 1.5.0+ (download the latest version from the JRuby site).
  • Java JRE or JDK 1.5+ (OpenJDK 1.6+ is also supported)

Installing JRuby R2CORBA

Download the latest R2CORBA source package from the File section and unpack at a location of your choice.
Next we need a binary distribution of JacORB (check the documentation included with R2CORBA for supported versions) for which the simplest option is to download a binary distribution archive from the JacORB site.
Create a jacorb directory under the directory created from the unpacked R2CORBA archive and unpack the downloaded JacORB archive there creating bin, lib, @etc and other subdirectories.

After unpacking the archives move to the unpacked R2CORBA directory.
In that directory configure R2CORBA as follows:

$ rake configure

When this step has succeeded you can 'build’ the R2CORBA JRuby extension as follows:

$ rake build

This step prepares the R2CORBA JRuby extensions and compiles a number of core IDL files using the RIDL compiler.
When 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:

$ rake test

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

...
Finished tests in 31.667355s, 1.0421 tests/s, 0.0000 assertions/s.
33 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 JRuby installation as follows (be aware that on Linux special requirements may apply for installing):

$ rake install

These instructions you can also find in the INSTALL.jruby file (source:INSTALL.jruby) which is part of the unpacked files from the R2CORBA archive.

Custom Gem installation

As described above R2CORBA Gem installation by default installs a platform dependent version and automatically provides a matching ORB (TAO or JacORB) installation (either prebuilt binaries or an automatically built platform specific version).
In case you want to install the R2CORBA Gem without the automatically provided ORB binaries but instead want to configure the Gem to use a pre-installed ORB version you can execute the gem install command with custom build-flags (see also the output of the gem help install command for info concerning custom build-flags) in the following way.

MRI Gem customization

Installing the R2CORBA Gem for an MRI platform with a pre-installed TAO version requires the installation of the source-only version. This is the default for MRI on Linux and can be forced on Windows by adding the --platform ruby switch.
To specifiy to the Gem installation scripts that a pre-installed TAO version is to be used the --without-taogem build flag must be added.
Lastly it is needed to provide the locations of ACE,TAO and MPC to the Gem installation scripts by either defining the ACE_ROOT, TAO_ROOT and MPC_ROOT environment variables or adding the build flags --aceroot, --taoroot and --mpcroot. As always the paths for TAO_ROOT and MPC_ROOT default to $ACE_ROOT/tao and $ACE_ROOT/MPC if not specified.
For generation of makefiles for the R2CORBA extension it is necessary that the correct mwc.pl file can be located at $ACE_ROOT/bin.

The R2CORBA Gem could thus be custom installed on Linux with a command like:

$ gem install -- --without-taogem --aceroot=/usr/local/src/ACE_wrappers

or

$ ACE_ROOT=/usr/local/src/ACE_wrappers gem install -- --without-taogem

On Windows this could be achieved like:

> gem install --platform ruby -- --without-taogem --aceroot=C:/Develop/ACE_wrappers

NOTE: Be aware that these commands only provide the possibility to configure and build R2CORBA for pre-installed versions of TAO. For runtime execution it is required that the system is configured correctly such that the R2CORBA extension libraries are able find the necessary ACE and TAO shared libraries.

JRuby Gem customization

Installing the R2CORBA Gem for a pre-installed version of JacORB can be achieved in similar ways by forcing install of the source-only Gem and specifying a JacOrb home location as follows:

$ gem install --platform ruby -- --jacorb-home=/usr/lib/jacorb 

or

$ JACORB_HOME=/usr/lib/jacorb gem install --platform ruby

Custom installation on Windows follows the same approach here.