BuildInstruction fixes

- Hard-wrapped lines to 80 cols
- Added OSX instruction for Ruby

1 files changed, 153 insertions, 0 deletions

diff --git a/ruby/BuildInstructionsLinuxOSX.md b/ruby/BuildInstructionsLinuxOSX.md
new file mode 100644
index 00000000000..56b4ec9fd76
--- /dev/null
+++ b/ruby/BuildInstructionsLinuxOSX.md
@@ -0,0 +1,153 @@
+# Building Ice for Ruby on Linux
+
+This file describes how to build and install Ice for Ruby from source code on
+Linux and OS X. If you prefer, you can also download [binary distributions][1]
+for the supported platforms.
+
+## Ruby Build Requirements
+
+### Operating Systems and Compilers
+
+Ice for Ruby is expected to build and run properly on OS X and on any recent
+Linux distribution for x86 and x86_64, and was extensively tested using the
+operating systems and Ruby versions listed for our [supported platforms][2].
+
+### Ruby Versions
+
+Ice for Ruby supports Ruby versions 1.8.1 or later. 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)
+
+### Ice Development Kit
+
+You will need the Ice development kit for C++, which you can install as a binary
+distribution or compile from source yourself.
+
+## Building the Ruby Extension
+
+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
+
+If you have not built Ice for C++ in the `cpp` subdirectory, set `ICE_HOME`
+to the directory of your Ice for C++ installation. For example:
+
+    $ export ICE_HOME=/opt/Ice
+
+Change to the Ice for Ruby source subdirectory:
+
+    $ cd ruby
+
+Edit `config/Make.rules`and adjust as necessary. For example, you may wish to
+enable `OPTIMIZE`.
+
+Run `make` to build the extension.
+
+## Installing Ice for Ruby
+
+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 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>/ruby/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.
+
+## Configuring your Environment for Ruby
+
+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/ruby:$RUBYLIB
+
+This example assumes that your Ice for Ruby installation is located in the
+`/opt/Ice` directory.
+
+You must also modify `LD_LIBRARY_PATH` or `DYLD_LIBRARY_PATH` to include the
+directory `/opt/Ice/lib`:
+
+    $ export LD_LIBRARY_PATH=/opt/Ice/lib:$LD_LIBRARY_PATH       (Linux)
+    $ export DYLD_LIBRARY_PATH=/opt/Ice/lib:$DYLD_LIBRARY_PATH   (OS X)
+
+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 Ruby Tests
+
+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`.
+
+## SELinux Notes for Ruby
+
+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:
+
+- Change the default security context for the Ice extension using the following
+command:
+
+        $ chcon -t texrel_shlib_t /opt/Ice/ruby/IceRuby.so
+
+    Replace `/opt/Ice` with your installation directory.
+
+- Disable SELinux completely by adding the following line to your
+`/etc/sysconfig/selinux` file:
+
+        SELINUX=disabled
+
+[1]: https://zeroc.com/download.html
+[2]: https://doc.zeroc.com/display/Ice36/Supported+Platforms+for+Ice+3.6.0