rb/INSTALL.WINDOWS

   1 ======================================================================
   2 Requirements
   3 ======================================================================
   4
   5
   6 Operating System
   7 ----------------
   8
   9 Ice for Ruby is only supported on Windows XP.
  10
  11
  12 Build Environment
  13 -----------------
  14
  15 To build Ice for Ruby you must have the following:
  16
  17  - Ice 3.4.2 for C++
  18  - Visual C++ 6.0 SP5 with STLport 4.6.2 (or later)*
  19  - Ruby 1.8.6
  20
  21 * Ruby requires Visual C++ 6.0, therefore it is the only compiler
  22   supported by Ice for Ruby.
  23
  24 The instructions in this file make the following assumptions about
  25 your build environment:
  26
  27 1. You have installed the Ice 3.4.2 for Visual C++ 6.0 distribution
  28    using the installer available at the link below:
  29
  30    http://www.zeroc.com/download.html
  31
  32    The default installation directory is the following:
  33
  34    C:\Program Files\ZeroC\Ice-3.4.2
  35
  36 2. You have installed Ruby using the Windows installer available at
  37    RubyForge:
  38
  39    http://rubyforge.org/projects/rubyinstaller/
  40
  41    The default installation directory is C:\ruby.
  42
  43 If you selected different installation directories, you will need to
  44 modify the relevant path names in the steps below to match your
  45 configuration.
  46
  47
  48 ======================================================================
  49 Compilation and Testing
  50 ======================================================================
  51
  52
  53 Compiling Ice for Ruby
  54 ----------------------
  55
  56 Follow these steps to build the Ice extension for Ruby:
  57
  58 1) Open a command prompt that supports command-line compilation with
  59    Visual C++. For example, you can execute the Visual C++ batch file
  60    vcvars32.bat to configure your environment. Alternatively, you can
  61    start a "Visual Studio Command Prompt" by selecting the appropriate
  62    entry from the Visual Studio program group in your Start menu.
  63
  64 2) Change to the Ice for Ruby source directory:
  65
  66    > cd Ice-3.4.2\rb
  67
  68 3) If you installed the Ice 3.4.2 for Visual C++ 6.0 distribution in a
  69    non-standard location, set the ICE_HOME environment variable with
  70    the Ice installation directory. For example:
  71
  72    > set ICE_HOME=C:\Ice-3.4.2
  73
  74 4) Edit config\Make.rules.mak and review the settings. In particular
  75    you must set CPP_COMPILER to the appropriate compiler.
  76
  77 5) Run nmake:
  78
  79    > nmake /f Makefile.mak
  80
  81 If no errors occurred, you can now begin using Ice for Ruby.
  82
  83 NOTES:
  84
  85  * Normally you should build with OPTIMIZE=yes. If you are using a
  86    Ruby interpreter that was compiled in debug mode, set OPTIMIZE=no
  87    and edit ruby/Ice.rb to change the line below from
  88
  89    require "IceRuby"
  90
  91    to the following:
  92
  93    require "IceRubyd"
  94
  95
  96 Running the tests
  97 -----------------
  98
  99 The test subdirectory contains Ruby implementations of the core Ice
 100 test suite. Python is required to run the test suite:
 101
 102   http://www.python.org/download
 103
 104 The test suites require that the Ice for C++ tests be built in the cpp
 105 subdirectory of this source distribution.
 106
 107 Open a command window and change to the top-level directory. At the
 108 command prompt, execute:
 109
 110   > python allTests.py
 111
 112 You can also run tests individually by changing to the test directory
 113 and running this command:
 114
 115   > python run.py
 116
 117 If everything worked out, you should see lots of "ok" messages. In
 118 case of a failure, the tests abort with "failed".
 119
 120
 121 ======================================================================
 122 Installation
 123 ======================================================================
 124
 125 You can perform an automated installation with the following command:
 126
 127   > nmake /f Makefile.mak install
 128
 129 This process uses the "prefix" variable in config\Make.rules.mak as
 130 the installation's root directory. The subdirectory <prefix>\ruby is
 131 created as a copy of the local "ruby" directory and contains the Ice
 132 for Ruby extension library (IceRuby.dll) as well as Ruby source code.
 133 Using this installation method requires that you modify your
 134 environment as described in "Using Ice for Ruby" below.
 135
 136
 137 ======================================================================
 138 Using Ice for Ruby
 139 ======================================================================
 140
 141
 142 Configuring your environment
 143 ----------------------------
 144
 145 The Ruby interpreter must be able to locate the Ice extension. One way
 146 to configure the interpreter is to define the RUBYLIB environment
 147 variable as follows:
 148
 149   > set RUBYLIB=C:\Ice-3.4.2\ruby
 150
 151 This example assumes your Ice for Ruby installation is located in the
 152 C:\Ice-3.4.2 directory.
 153
 154 In addition, you must modify your PATH environment variable to include
 155 the following directories:
 156
 157   C:\Program Files\ZeroC\Ice-3.4.2\bin
 158   C:\Ice-3.4.2\bin
 159
 160 At a command prompt, you can set your PATH as shown below:
 161
 162   > set PATH=C:\Program Files\ZeroC\Ice-3.4.2\bin;C:\Ice-3.4.2\bin;%PATH%
 163
 164
 165 Testing your installation
 166 -------------------------
 167
 168 To verify that Ruby can load the Ice extension successfully, open a
 169 command window and start the interpreter using irb.bat:
 170
 171   > irb.bat
 172   irb(main):001:0>
 173
 174 At the prompt, enter
 175
 176   require "Ice"
 177
 178 If the interpreter responds with the value "true", the Ice extension
 179 was loaded successfully. Enter "exit" to quit the interpreter.
 180
 181
 182 Running the demos
 183 -----------------
 184
 185 The demos directory contains Ruby versions of the Ice sample programs.
 186 Note that only clients are provided, since Ice for Ruby does not
 187 support server-side activities. In order to run a sample client, you
 188 must first start its corresponding server from another Ice language
 189 mapping, such as C++.
 190
 191 As an example, let's run the hello application in demo\Ice\hello using
 192 the C++ server. Assuming that you have extracted the Ice demo archive
 193 into C:\Ice-3.4.2-demos, and that you have already compiled the sample
 194 C++ programs, we begin by starting the server:
 195
 196   > cd \Ice-3.4.2-demos\demo\Ice\hello
 197   > server
 198
 199 In a separate window, start the client:
 200
 201   > cd Ice-3.4.2\rb\demo\Ice\hello
 202   > ruby Client.rb
 203
 204 Some demo directories contain README files if additional requirements
 205 are necessary.
 206
 207
 208 ======================================================================
 209 Notes
 210 ======================================================================
 211
 212
 213 Limitations
 214 -----------
 215
 216 Ruby's lack of support for native threads makes it impractical for
 217 ZeroC to implement server-side functionality, therefore Ice for Ruby
 218 can only be used in client applications. If you have a need for this
 219 feature and wish to sponsor its development, please contact us at
 220 info@zeroc.com.
 221
 222
 223 OpenSSL Compatibility Issue
 224 ---------------------------
 225
 226 The Ruby installer includes versions of the OpenSSL DLLs that are not
 227 compatible with the ones supplied with Ice. If you intend to use SSL
 228 in your Ice for Ruby applications, you will need to remove or rename
 229 the following files in the Ruby installation directory:
 230
 231   libeay32.dll
 232   ssleay32.dll
 233
 234 If you used the default installation directory, these files are
 235 located in C:\ruby\bin.
 236
 237 Also be aware that the Ruby installer inserts C:\ruby\bin at the
 238 beginning of the system PATH, therefore the DLLs listed above can also
 239 have an adverse impact on other Ice language mappings that use
 240 OpenSSL, such as C++ and Python.