ICE-6494 - build instructions

2 files changed, 230 insertions, 0 deletions

diff --git a/ruby/BuildInstructionsLinux.md b/ruby/BuildInstructionsLinux.md
new file mode 100644
index 00000000000..b05879c8c32
--- /dev/null
+++ b/ruby/BuildInstructionsLinux.md
@@ -0,0 +1,116 @@
+# Building Ice for Ruby on Linux
+
+This page describes how to build and install Ice for Ruby from source code. If you prefer, you can also download [binary distributions](https://zeroc.com/download.html) for the supported platforms.
+
+## Ruby Build Requirements
+
+### Operating Systems and Compilers
+
+Ice for Ruby is expected to build and run properly 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](https://zeroc.com/platforms_3_6_0.html).
+
+### 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 (```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>/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``` to include the directory ```/opt/Ice/lib```:
+
+    $ export LD_LIBRARY_PATH=/opt/Ice/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.
+
+## 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```
diff --git a/ruby/BuildInstructionsWindows.md b/ruby/BuildInstructionsWindows.md
new file mode 100644
index 00000000000..2a067cc30ae
--- /dev/null
+++ b/ruby/BuildInstructionsWindows.md
@@ -0,0 +1,114 @@
+# Building Ice for Ruby on Windows
+
+This page describes how to build and install Ice for Ruby from source code. If you prefer, you can also download [binary distributions](https://zeroc.com/download.html) for the supported platforms.
+
+## Ruby Build Requirements
+
+### Operating Systems
+
+Ice for Ruby is expected to build and run properly on Windows, and was extensively tested using the operating systems and Ruby versions listed for our [supported platforms](https://zeroc.com/platforms_3_6_0.html).
+
+### Prerequisites
+
+To build Ice for Ruby you must have the following:
+
+- Ice 3.6 development kit for C++
+- Ruby 2.2
+- Ruby Development Kit 4.7.2
+- mingw 4.7.3 (only for 32-bit builds)
+
+The Ruby distribution for Windows uses the MinGW compiler, therefore MinGW is the only C++ compiler supported by Ice for Ruby.
+
+The instructions in this file make the following assumptions about your build environment:
+
+1. You have installed the Ice 3.6.0 distribution using the ZeroC installer. The default installation directory is ```C:\Program Files (x86)\ZeroC\Ice-3.6.0```.
+1. You have installed Ruby 2.2.1 using the Windows installer. The default installation directory is ```C:\Ruby221```.
+1. You have installed the Ruby Development Kit 4.7.2 in ```C:\RubyDevKit-4.7.2```.
+1. For 32-bit builds, you have installed mingw 4.7.3 in ```C:\mingw-4.7.3```.
+
+If you selected different installation directories, you will need to modify the relevant path names in the steps below to match your configuration.
+
+## Building the Ruby Extension
+
+Open a Windows command prompt and add Ruby to your environment:
+
+    > C:\Ruby221\bin\setrbvars.bat
+
+Run the ```devkitvars.bat``` batch file from the Ruby development kit to setup your environment:
+
+    > C:\RubyDevKit-4.7.2\devkitvars.bat
+
+If you are building for Windows 32-bit:
+
+1. Add mingw 4.7.3 to your PATH, before the mingw 4.7.2 included in the Ruby development kit:
+
+   ```> set PATH=C:\mingw-4.7.3\bin;%PATH%```
+
+1. Then double-check the desired version of g++ is in your PATH:
+
+   ```> g++ -dumpversion```
+   ```4.7.3```
+
+Change to the Ice for Ruby source directory:
+
+    > cd ruby
+
+If you have not built Ice for C++ in 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.6.0
+
+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
+
+## 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 (```IceRuby.so```) as well as Ruby source code. Using this installation method requires that you modify your environment as described below.
+
+## Configuring your Environment for Ruby
+
+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.6.0\ruby
+
+This example assumes your Ice for Ruby installation is located in the ```C:\Ice-3.6.0``` directory.
+
+In addition, you must modify your PATH environment variable to include the following directories:
+
+    C:\Program Files (x86)\ZeroC\Ice-3.6.0\bin
+    C:\Ice-3.6.0\bin
+
+At a command prompt, you can set your PATH as shown below:
+
+    > set PATH=C:\Program Files (x86)\ZeroC\Ice-3.6.0\bin;C:\Ice-3.6.0\bin;%PATH%
+
+## 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```.