This page describes how to build and install Ice for Ruby from source code. If you prefer, you can also download binary distributions for the supported platforms.
On this page:
Ice for Ruby is expected to build and run properly on Windows and any recent Linux distribution for x86 and x86_64, and was extensively tested using the operating systems and Ruby versions listed on our platforms page.
Ruby currently does not implement server-side functionality, therefore Ice for Ruby can only be used in client applications. If you have a need for this feature and wish to sponsor its development, please contact us at info@zeroc.com. |
To build Ice for Ruby you must have the following:
You can use a source or binary installation of Ruby. If you use an RPM installation, the following packages are required:
ruby
ruby-devel
ruby-libs (RHEL)
To build Ice for Ruby you must have the following:
The Ruby distribution for Windows uses the MinGW compiler, therefore MinGW is the only compiler supported by Ice for Ruby.
The instructions in this file make the following assumptions about your build environment:
C:\Program Files\ZeroC\Ice-3.5.1
.C:\Ruby193
.If you selected different installation directories, you will need to modify the relevant path names in the steps below to match your configuration.
The instructions for compiling the Ice extension assume that you have already installed Ruby.
If you installed Ruby in a non-standard location, set the RUBY_HOME
environment variable to the installation directory. For example:
$ export RUBY_HOME=/opt/ruby-1.8.6
If you have not built Ice for C++ from the cpp
subdirectory or if you have installed the Ice for C++ development kit in a non-standard location, set the ICE_HOME
environment variable to the installation directory. For example:
$ export ICE_HOME=/opt/Ice-3.5.1
Review the settings in config/Make.rules
and adjust as necessary. For example, you may wish to enable OPTIMIZE
.
Run make to build the extension.
Follow the steps below to build the Ice extension for Ruby.
Open a Windows command prompt and add Ruby to your environment:
> C:\Ruby193\bin\setrbvars.bat
Add MinGW from the Ruby Development Kit to your PATH
:
> C:\RubyDevKit-4.5.2\devkitvars.bat
Change to the Ice for Ruby source directory:
> cd Ice-3.5.1/rb
If you have not built Ice for C++ from the cpp
subdirectory, set the ICE_HOME
environment variable to point to your Ice installation. This path must contain forward slashes (/) as directory separators, and cannot contain any space. If your Ice installation's path contains any space, use the DOS 8-character name as a work-around, for example:
> set ICE_HOME=C:/PROGRA~2/Ice-3.5.1
You can use dir /x
to get this DOS name, for example:
> cd c:\
> dir /x
Directory of c:\
...
03/03/2014 03:37 PM <DIR> PROGRA~1 Program Files
07/25/2014 12:54 PM <DIR> PROGRA~2 Program Files (x86)
Then run make to build the extension:
> make
You can perform an automated installation with the following command:
$ make install
This process uses the prefix
variable in config/Make.rules
as the installation's root directory. The subdirectory prefix/ruby
is created as a copy of the local ruby
directory and contains the Ice for Ruby extension library (IceRuby.so
) as well as Ruby source code. Using this installation method requires that you modify your environment as described in "Using Ice for Ruby" below.
Another option is to copy the contents of the local ruby
directory to your Ruby installation's site_ruby
directory. For example, if you installed Ruby via RPM, you can use the steps below:
# cd <Ice source directory>/rb/ruby
# sudo tar cf - * | (cd /usr/lib/ruby/site_ruby/1.8/i386-linux; tar xvf -)
On x86_64 systems, change the last command to:
# sudo tar cf - * | (cd /usr/lib64/ruby/site_ruby/1.8/x86_64-linux; tar xvf -)
There is no need to modify your environment if you use this approach.
You can perform an automated installation with the following command:
> make install
This process uses the prefix
variable in config\Make.rules
as the installation's root directory. The subdirectory prefix\ruby
is created as a copy of the local ruby
directory and contains the Ice for Ruby extension library (IceRuby.so
) as well as Ruby source code. Using this installation method requires that you modify your environment as described below.
The Ruby interpreter must be able to locate the Ice extension. If you used the automated installation described above, you need to define the RUBYLIB
environment variable as follows:
$ export RUBYLIB=/opt/Ice-3.5.1/ruby:$RUBYLIB
This example assumes that your Ice for Ruby installation is located in the /opt/Ice-3.5.1
directory.
You must also modify LD_LIBRARY_PATH
to include the directory /opt/Ice-3.5.1/lib
:
$ export LD_LIBRARY_PATH=/opt/Ice-3.5.1/lib:LD_LIBRARY_PATH
To verify that Ruby can load the Ice extension successfully, open a command window and start the interpreter using irb
:
> irb
irb(main):001:0>
At the prompt, enter
require "Ice"
If the interpreter responds with the value true
, the Ice extension was loaded successfully. Enter exit
to quit the interpreter.
The Ruby interpreter must be able to locate the Ice extension. One way to configure the interpreter is to define the RUBYLIB
environment variable as follows:
> set RUBYLIB=C:\Ice-3.5.1\ruby
This example assumes your Ice for Ruby installation is located in the C:\Ice-3.5.1
directory.
In addition, you must modify your PATH
environment variable to include the following directories:
C:\Program Files\ZeroC\Ice-3.5.1\bin
C:\Ice-3.5.1\bin
At a command prompt, you can set your PATH
as shown below:
> set PATH=C:\Program Files\ZeroC\Ice-3.5.1\bin;C:\Ice-3.5.1\bin;%PATH%
The test subdirectory contains Ruby implementations of the core Ice test suite. Python is required to run the test suite.
The test suites require that the Ice for C++ tests be built in the cpp
subdirectory of this source distribution.
Open a command window and change to the top-level directory. At the command prompt, execute:
> python allTests.py
You can also run tests individually by changing to the test directory and running this command:
> python run.py
If everything worked out, you should see lots of "ok" messages. In case of a failure, the tests abort with "failed".
The demo directory contains Ruby versions of the Ice sample programs. Note that only clients are provided, since Ice for Ruby does not support server-side activities. In order to run a sample client, you must first start its corresponding server from another Ice language mapping, such as C++.
As an example, let's run the hello application in demo/Ice/hello using the C++ server. Assuming that you have already compiled the sample C++ programs in the cpp
subdirectory, we begin by starting the server:
> cd Ice-3.5.1/cpp/demo/Ice/hello
> server
In a separate window, start the client:
> cd Ice-3.5.1/rb/demo/Ice/hello
> ruby Client.rb
Some demo directories contain README
files if additional requirements are necessary.
If SELinux is enabled on your RHEL system, you may encounter this error message when Ruby attempts to load the Ice extension:
cannot restore segment prot after reloc: Permission denied
There are two ways to solve this problem:
$ chcon -t texrel_shlib_t /opt/Ice-3.5.0/ruby/IceRuby.so
/opt/Ice-3.5.1
with your installation directory./etc/sysconfig/selinux
file:SELINUX=disabled