====================================================================== Requirements ====================================================================== Operating System ---------------- Ice for Ruby is expected to build and run properly on any recent Linux distribution for x86 and x86_64. However, Ice for Ruby is officially supported only on: - Red Hat Enterprise Linux Advanced Server 4 Update 6 for i386 or x86_64 (RHEL 4.6) - Red Hat Enterprise Linux 5 Update 1 for i386 or x86_64 (RHEL 5.1) Build Environment ----------------- To build Ice for Ruby you must have the following: - Ice 3.3.1 for C++ development kit - Ruby 1.8.1 or later You can use a source or RPM installation of Ruby. If you prefer to use RPMs, the following packages are required: ruby ruby-libs ruby-devel ====================================================================== Compilation and Testing ====================================================================== Compiling Ice for Ruby ---------------------- The instructions for compiling the Ice extension assume that you have already installed Ruby. Follow these steps: 1. 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 2. If you have not built Ice for C++ from the cpp subdirectory or if you have installed the Ice 3.3.1 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.3.1 3. Review the settings in config/Make.rules and adjust as necessary. For example, you may wish to enable OPTIMIZE. 4. Run make. If no errors occurred, you can now begin using Ice for Ruby. Running the tests ----------------- The test subdirectory contains Ruby implementations of the core Ice test suite. Python is required to run the test suite: http://www.python.org/download 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". ====================================================================== Installation ====================================================================== 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 /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: $ su # cd /rb/ruby # tar cf - * | (cd /usr/lib/ruby/site_ruby/1.8/i386-linux; tar xvf -) On x86_64 systems, change the last command to: # 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. ====================================================================== Using Ice for Ruby ====================================================================== Configuring your environment ---------------------------- 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.3.1/ruby:$RUBYLIB This example assumes that your Ice for Ruby installation is located in the /opt/Ice-3.3.1 directory. You must also modify LD_LIBRARY_PATH to include the directory /opt/Ice-3.3.1/lib: $ export LD_LIBRARY_PATH=/opt/Ice-3.3.1/lib:LD_LIBRARY_PATH Testing your installation ------------------------- 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. Running the demos ----------------- The demos 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.3.1/cpp/demo/Ice/hello $ server In a separate window, start the client: $ cd Ice-3.3.1/rb/demo/Ice/hello $ ruby Client.rb Some demo directories contain README files if additional requirements are necessary. ====================================================================== Notes ====================================================================== Limitations ----------- Ruby's lack of support for native threads makes it impractical for ZeroC to 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. SELinux Issue on Red Hat Enterprise Linux ----------------------------------------- If SELinux is enabled on your 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: - Change the default security context for the Ice extension using the following command: $ chcon -t texrel_shlib_t /opt/Ice-3.3.1/ruby/IceRuby.so Replace /opt/Ice-3.3.1 with your installation directory. - Disable SELinux completely by adding the following line to your /etc/sysconfig/selinux file: SELINUX=disabled For more information on SELinux in Red Hat Enterprise Linux 4, refer to the link below: http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/