rb/INSTALL.LINUX

   1 ======================================================================
   2 Requirements
   3 ======================================================================
   4
   5
   6 Operating System
   7 ----------------
   8
   9 Ice for Ruby is expected to build and run properly on any recent Linux
  10 distribution for x86 and x86_64. However, Ice for Ruby is officially
  11 supported only on:
  12
  13  - Red Hat Enterprise Linux 6 for i386 or x86_64 (RHEL 6)
  14  - Red Hat Enterprise Linux 5 Update 4 for i386 or x86_64 (RHEL 5.4)
  15  - SuSE Linux Enterprise Server 11 for i386 or x86_64 (SLES 11)
  16
  17
  18 Build Environment
  19 -----------------
  20
  21 To build Ice for Ruby you must have the following:
  22
  23  - Ice 3.4.2 for C++ development kit
  24  - Ruby 1.8.1 or later
  25
  26 You can use a source or RPM installation of Ruby. If you prefer to use
  27 RPMs, the following packages are required:
  28
  29   ruby
  30   ruby-devel
  31   ruby-libs (RHEL)
  32
  33
  34 ======================================================================
  35 Compilation and Testing
  36 ======================================================================
  37
  38
  39 Compiling Ice for Ruby
  40 ----------------------
  41
  42 The instructions for compiling the Ice extension assume that you have
  43 already installed Ruby.
  44
  45 Follow these steps:
  46
  47 1. If you installed Ruby in a non-standard location, set the RUBY_HOME
  48    environment variable to the installation directory. For example:
  49
  50    $ export RUBY_HOME=/opt/ruby-1.8.6
  51
  52 2. If you have not built Ice for C++ from the cpp subdirectory or if
  53    you have installed the Ice 3.4.2 for C++ development kit in a
  54    non-standard location, set the ICE_HOME environment variable to the
  55    installation directory. For example:
  56
  57    $ export ICE_HOME=/opt/Ice-3.4.2
  58
  59 3. Review the settings in config/Make.rules and adjust as necessary.
  60    For example, you may wish to enable OPTIMIZE.
  61
  62 4. Run make.
  63
  64 If no errors occurred, you can now begin using Ice for Ruby.
  65
  66
  67 Running the tests
  68 -----------------
  69
  70 The test subdirectory contains Ruby implementations of the core Ice
  71 test suite. Python is required to run the test suite:
  72
  73   http://www.python.org/download
  74
  75 The test suites require that the Ice for C++ tests be built in the cpp
  76 subdirectory of this source distribution.
  77
  78 Open a command window and change to the top-level directory. At the
  79 command prompt, execute:
  80
  81   $ python allTests.py
  82
  83 You can also run tests individually by changing to the test directory
  84 and running this command:
  85
  86   $ python run.py
  87
  88 If everything worked out, you should see lots of "ok" messages. In
  89 case of a failure, the tests abort with "failed".
  90
  91
  92 ======================================================================
  93 Installation
  94 ======================================================================
  95
  96 You can perform an automated installation with the following command:
  97
  98   > make install
  99
 100 This process uses the "prefix" variable in config/Make.rules as the
 101 installation's root directory. The subdirectory <prefix>/ruby is
 102 created as a copy of the local "ruby" directory and contains the Ice
 103 for Ruby extension library (IceRuby.so) as well as Ruby source code.
 104 Using this installation method requires that you modify your
 105 environment as described in "Using Ice for Ruby" below.
 106
 107 Another option is to copy the contents of the local "ruby" directory
 108 to your Ruby installation's "site_ruby" directory. For example, if
 109 you installed Ruby via RPM, you can use the steps below:
 110
 111   $ su
 112   # cd <Ice source directory>/rb/ruby
 113   # tar cf - * | (cd /usr/lib/ruby/site_ruby/1.8/i386-linux; tar xvf -)
 114
 115 On x86_64 systems, change the last command to:
 116
 117   # tar cf - * | (cd /usr/lib64/ruby/site_ruby/1.8/x86_64-linux; tar xvf -)
 118
 119 There is no need to modify your environment if you use this approach.
 120
 121
 122 ======================================================================
 123 Using Ice for Ruby
 124 ======================================================================
 125
 126
 127 Configuring your environment
 128 ----------------------------
 129
 130 The Ruby interpreter must be able to locate the Ice extension. If you
 131 used the automated installation described above, you need to define
 132 the RUBYLIB environment variable as follows:
 133
 134   $ export RUBYLIB=/opt/Ice-3.4.2/ruby:$RUBYLIB
 135
 136 This example assumes that your Ice for Ruby installation is located in
 137 the /opt/Ice-3.4.2 directory.
 138
 139 You must also modify LD_LIBRARY_PATH to include the directory
 140 /opt/Ice-3.4.2/lib:
 141
 142   $ export LD_LIBRARY_PATH=/opt/Ice-3.4.2/lib:LD_LIBRARY_PATH
 143
 144
 145 Testing your installation
 146 -------------------------
 147
 148 To verify that Ruby can load the Ice extension successfully, open a
 149 command window and start the interpreter using irb:
 150
 151   $ irb
 152   irb(main):001:0>
 153
 154 At the prompt, enter
 155
 156   require "Ice"
 157
 158 If the interpreter responds with the value "true", the Ice extension
 159 was loaded successfully. Enter "exit" to quit the interpreter.
 160
 161
 162 Running the demos
 163 -----------------
 164
 165 The demos directory contains Ruby versions of the Ice sample programs.
 166 Note that only clients are provided, since Ice for Ruby does not
 167 support server-side activities. In order to run a sample client, you
 168 must first start its corresponding server from another Ice language
 169 mapping, such as C++.
 170
 171 As an example, let's run the hello application in demo/Ice/hello using
 172 the C++ server. Assuming that you have already compiled the sample C++
 173 programs in the cpp subdirectory, we begin by starting the server:
 174
 175   $ cd Ice-3.4.2/cpp/demo/Ice/hello
 176   $ server
 177
 178 In a separate window, start the client:
 179
 180   $ cd Ice-3.4.2/rb/demo/Ice/hello
 181   $ ruby Client.rb
 182
 183 Some demo directories contain README files if additional requirements
 184 are necessary.
 185
 186
 187 ======================================================================
 188 Notes
 189 ======================================================================
 190
 191
 192 Limitations
 193 -----------
 194
 195 Ruby's lack of support for native threads makes it impractical for
 196 ZeroC to implement server-side functionality, therefore Ice for Ruby
 197 can only be used in client applications. If you have a need for this
 198 feature and wish to sponsor its development, please contact us at
 199 info@zeroc.com.
 200
 201
 202 SELinux Issue on Red Hat Enterprise Linux
 203 -----------------------------------------
 204
 205 If SELinux is enabled on your system, you may encounter this error
 206 message when Ruby attempts to load the Ice extension:
 207
 208   "cannot restore segment prot after reloc: Permission denied"
 209
 210 There are two ways to solve this problem:
 211
 212 - Change the default security context for the Ice extension using the
 213   following command:
 214
 215   $ chcon -t texrel_shlib_t /opt/Ice-3.4.2/ruby/IceRuby.so
 216
 217   Replace /opt/Ice-3.4.2 with your installation directory.
 218
 219 - Disable SELinux completely by adding the following line to your
 220   /etc/sysconfig/selinux file:
 221
 222   SELINUX=disabled
 223
 224 For more information on SELinux in Red Hat Enterprise Linux, refer to
 225 the link below:
 226
 227   http://docs.redhat.com/docs/en-US/Red_Hat_Enterprise_Linux/5/html/Deployment_Guide/selg-overview.html