1# Building Ice for Ruby on Linux and macOS 2 3This file describes how to build and install Ice for Ruby from source code on 4Linux and macOS. If you prefer, you can also download [binary distributions][1] 5for the supported platforms. 6 7* [Ruby Build Requirements](#ruby-build-requirements) 8 * [Operating Systems and Compilers](#operating-systems-and-compilers) 9 * [Ruby Versions](#ruby-versions) 10* [Building the Ruby Extension](#building-the-ruby-extension) 11* [Installing Ice for Ruby](#installing-ice-for-ruby) 12* [Configuring your Environment for Ruby](#configuring-your-environment-for-ruby) 13* [Running the Ruby Tests](#running-the-ruby-tests) 14* [SELinux Notes for Ruby](#selinux-notes-for-ruby) 15 16## Ruby Build Requirements 17 18### Operating Systems and Compilers 19 20Ice for Ruby is expected to build and run properly on macOS and on any recent 21Linux distribution for x86 and x86_64, and was extensively tested using the 22operating systems and Ruby versions listed for our [supported platforms][2]. 23 24### Ruby Versions 25 26Ice for Ruby supports Ruby versions 1.8.1 or later. You can use a source or 27binary installation of Ruby. 28 29If you use an RPM installation, the following packages are required: 30``` 31ruby 32ruby-devel 33ruby-libs (RHEL) 34``` 35 36## Building the Ruby Extension 37 38The instructions for compiling the Ice extension assume that you have already 39installed Ruby. 40 41If you installed Ruby in a non-standard location, set the `RUBY_HOME` 42environment variable to the installation directory. For example: 43``` 44export RUBY_HOME=/opt/ruby 45```` 46 47The build of Ice for Ruby requires that you first build Ice for C++ in the 48`cpp` subdirectory. 49 50From the top-level source directory, edit `config/Make.rules` to establish your 51build configuration. The comments in the file provide more information. 52 53Change to the Ice for Ruby source subdirectory: 54``` 55cd ruby 56``` 57 58Run `make` to build the extension. 59 60## Installing Ice for Ruby 61 62You can perform an automated installation with the following command: 63``` 64make install 65``` 66 67This process uses the `prefix` variable in `../config/Make.rules` as the 68installation's root directory. The subdirectory `<prefix>/ruby` is created as a 69copy of the local `ruby` directory and contains the Ice for Ruby extension 70library as well as Ruby source code. Using this installation method requires 71that you modify your environment as described in *Using Ice for Ruby* below. 72 73Another option is to copy the contents of the local `ruby` directory to your 74Ruby installation's `site_ruby` directory. For example, if you installed Ruby 75via RPM, you can use the steps below: 76``` 77cd <Ice source directory>/ruby/ruby 78sudo tar cf - * | (cd /usr/lib/ruby/site_ruby/1.8/i386-linux; tar xvf -) 79``` 80 81On x86_64 systems, change the last command to: 82``` 83sudo tar cf - * | (cd /usr/lib64/ruby/site_ruby/1.8/x86_64-linux; tar xvf -) 84``` 85 86There is no need to modify your environment if you use this approach. 87 88## Configuring your Environment for Ruby 89 90The Ruby interpreter must be able to locate the Ice extension. If you used the 91automated installation described above, you need to define the `RUBYLIB` 92environment variable as follows: 93``` 94export RUBYLIB=/opt/Ice/ruby:$RUBYLIB 95``` 96 97This example assumes that your Ice for Ruby installation is located in the 98`/opt/Ice` directory. 99 100You must also modify `LD_LIBRARY_PATH` or `DYLD_LIBRARY_PATH` to include the 101directory `/opt/Ice/lib`: 102``` 103export LD_LIBRARY_PATH=/opt/Ice/lib:$LD_LIBRARY_PATH (Linux) 104export DYLD_LIBRARY_PATH=/opt/Ice/lib:$DYLD_LIBRARY_PATH (macOS) 105``` 106 107To verify that Ruby can load the Ice extension successfully, open a command 108window and start the interpreter using `irb`. 109 110At the prompt, enter: 111``` 112require "Ice" 113``` 114 115If the interpreter responds with the value true, the Ice extension was loaded 116successfully. Enter `exit` to quit the interpreter. 117 118## Running the Ruby Tests 119 120The `test` subdirectory contains Ruby implementations of the core Ice test 121suite. Python is required to run the test suite. 122 123The test suites require that the Ice for C++ tests be built in the `cpp` 124subdirectory of this source distribution. 125 126Open a command window and change to the top-level directory. At the command 127prompt, execute: 128``` 129python allTests.py 130``` 131 132You can also run tests individually by changing to the test directory and 133running this command: 134``` 135python run.py 136``` 137 138If everything worked out, you should see lots of `ok` messages. In case of a 139failure, the tests abort with `failed`. 140 141## SELinux Notes for Ruby 142 143If SELinux is enabled on your RHEL system, you may encounter this error message 144when Ruby attempts to load the Ice extension: 145``` 146cannot restore segment prot after reloc: Permission denied 147``` 148There are two ways to solve this problem: 149 150- Change the default security context for the Ice extension using the following 151command: 152 153 ``` 154 chcon -t texrel_shlib_t /opt/Ice/ruby/IceRuby.so 155 ``` 156 157Replace `/opt/Ice` with your installation directory. 158 159- Disable SELinux completely by adding the following line to your 160`/etc/sysconfig/selinux` file: 161 162 ``` 163 SELINUX=disabled 164 ``` 165 166[1]: https://zeroc.com/distributions/ice 167[2]: https://doc.zeroc.com/display/Rel/Supported+Platforms+for+Ice+3.7.2 168