[ruby-oci8-commit] [496] trunk/ruby-oci8: add and fix documents.

nobody at rubyforge.org nobody at rubyforge.org
Sun Mar 11 11:59:32 UTC 2012


Revision: 496
Author:   kubo
Date:     2012-03-11 11:59:32 +0000 (Sun, 11 Mar 2012)
Log Message:
-----------
add and fix documents.

Modified Paths:
--------------
    trunk/ruby-oci8/ChangeLog
    trunk/ruby-oci8/dist-files
    trunk/ruby-oci8/docs/install-full-client.md

Added Paths:
-----------
    trunk/ruby-oci8/docs/install-instant-client.md
    trunk/ruby-oci8/docs/platform-specific-issues.md

Modified: trunk/ruby-oci8/ChangeLog
===================================================================
--- trunk/ruby-oci8/ChangeLog	2012-03-11 11:36:17 UTC (rev 495)
+++ trunk/ruby-oci8/ChangeLog	2012-03-11 11:59:32 UTC (rev 496)
@@ -1,4 +1,8 @@
 2012-03-11  KUBO Takehiro  <kubo at jiubao.org>
+	* dist-files, docs/install-full-client.md, docs/install-instant-client.md,
+	  docs/platform-specific-issues.md: add and fix documents.
+
+2012-03-11  KUBO Takehiro  <kubo at jiubao.org>
 	* ruby-oci8.gemspec: fix warning: string literal in condition.
 	    (pointed by andynu at github)
 

Modified: trunk/ruby-oci8/dist-files
===================================================================
--- trunk/ruby-oci8/dist-files	2012-03-11 11:36:17 UTC (rev 495)
+++ trunk/ruby-oci8/dist-files	2012-03-11 11:59:32 UTC (rev 496)
@@ -9,6 +9,8 @@
 ruby-oci8.gemspec
 setup.rb
 docs/install-full-client.md
+docs/install-instant-client.md
+docs/platform-specific-issues.md
 ext/oci8/.document
 ext/oci8/MANIFEST
 ext/oci8/apiwrap.c.tmpl

Modified: trunk/ruby-oci8/docs/install-full-client.md
===================================================================
--- trunk/ruby-oci8/docs/install-full-client.md	2012-03-11 11:36:17 UTC (rev 495)
+++ trunk/ruby-oci8/docs/install-full-client.md	2012-03-11 11:59:32 UTC (rev 496)
@@ -41,20 +41,17 @@
 Installation
 ============
 
-Download the source code
-------------------------
+If you get a problem in the following steps, look at {file:docs/platform-specific-issues.md}
+and {file:docs/report-installation-issue.md}.
 
-Download the latest tar.gz package such as ruby-oci8 2.1.0.tar.gz,
-which is the latest version at the time of writing, from [rubyforge][].
-
 Set the library search path
------------------------
+---------------------------
 
 ### UNIX
 
 Set the library search path, whose name depends on the OS, to point to
-$ORACLE_HOME/lib. If the database is 64-bit and the ruby is 32-bit,
-use $ORACLE_HOME/lib32 instead.
+$ORACLE\_HOME/lib. If the database is 64-bit and the ruby is 32-bit,
+use $ORACLE\_HOME/lib32 instead.
 
 <table style="border: 1px #E3E3E3 solid; border-collapse: collapse; border-spacing: 0;">
 <thead>
@@ -81,20 +78,34 @@
 
 If sqlplus runs correctly, library search path has no problem.
 
-Run make and install
---------------------
+gem package
+-----------
 
-### UNIX or Windows(mingw32, cygwin)
+Run the following command.
 
+    gem install ruby-oci8
+
+tar.gz package
+--------------
+
+### Download the source code
+
+Download the latest tar.gz package such as ruby-oci8 2.1.0.tar.gz,
+which is the latest version at the time of writing, from [rubyforge][].
+
+### Run make and install
+
+#### UNIX or Windows(mingw32, cygwin)
+
     gzip -dc ruby-oci8-VERSION.tar.gz | tar xvf -
     cd ruby-oci8-VERSION
     make
     make install
 
-note: If you use '''sudo''', use it only when running 'make install'.
-sudo doesn't pass library search path to the executing command for security reasons.
+note: If you use '`sudo`', use it only when running '`make install`'.
+'`sudo`' doesn't pass library search path to the executing command for security reasons.
 
-### Windows(mswin32)
+#### Windows(mswin32)
 
 
     gzip -dc ruby-oci8-VERSION.tar.gz | tar xvf -
@@ -102,7 +113,4 @@
     nmake
     nmake install
 
-If you have a problem, look at {file:docs/platform-specific-issues.md}
-and {file:docs/report-installation-issue.md}.
-
 [rubyforge]: http://rubyforge.org/frs/?group_id=256

Added: trunk/ruby-oci8/docs/install-instant-client.md
===================================================================
--- trunk/ruby-oci8/docs/install-instant-client.md	                        (rev 0)
+++ trunk/ruby-oci8/docs/install-instant-client.md	2012-03-11 11:59:32 UTC (rev 496)
@@ -0,0 +1,167 @@
+# @title Install for Oracle Instant Client
+
+Introduction
+============
+
+This page explains the way to install ruby-oci8 for Oracle Instant Client.
+
+For Oracle Full Client, look at {file:docs/install-full-client.md}.
+For Windows, look at {file:docs/install-binary-package.md} unless you
+have a special need to compile ruby-oci8 by yourself.
+
+Install Oracle Instant Client Packages
+======================================
+
+Donwload Instant Client Packages
+--------------------------------
+Download the following packages from [Oracle Technology Network](http://www.oracle.com/technetwork/database/features/instant-client/index-097480.html).
+
+* Instant Client Package - Basic or Basic Lite
+* Instant Client Package - SDK
+* Instant Client Package - SQL*Plus
+
+Note: use 32-bit packages for 32-bit ruby even though the OS is 64-bit.
+
+UNIX zip packages
+-----------------
+
+Unzip the packages as follows:
+
+    mkdir /opt
+    mkdir /opt/oracle
+    cd /opt/oracle
+    unzip path/to/instantclient-basic-OS-VERSION.zip
+    unzip path/to/instantclient-sdk-OS-VERSION.zip
+    unzip path/to/instantclient-sqlplus-OS-VERSION.zip
+
+If /opt/oracle/instantclient10_1/libclntsh.so is not found, make
+a symbolic link to link the library.
+
+    cd /opt/oracle/instantclient10_1
+    ln -s libclntsh.so.10.1 libclntsh.so
+
+Note:
+
+* use libclntsh.sl instead of libclntsh.so on HP-UX PA-RISC.
+* use libclntsh.dylib instead of libclntsh.so on Mac OS X.
+* skip this step for AIX.
+
+Set the library search path, whose name depends on the OS, to point to
+the installed directory.
+
+<table style="border: 1px #E3E3E3 solid; border-collapse: collapse; border-spacing: 0;">
+<thead>
+  <tr><th> OS                        </th><th> library search path                   </th></tr>
+</thead>
+<tbody>
+  <tr><td> Linux                     </td><td> LD_LIBRARY_PATH                       </td></tr>
+  <tr><td> Solaris 32-bit ruby       </td><td> LD_LIBRARY_PATH_32 or LD_LIBRARY_PATH </td></tr>
+  <tr><td> Solaris 64-bit ruby       </td><td> LD_LIBRARY_PATH_64 or LD_LIBRARY_PATH </td></tr>
+  <tr><td> HP-UX PA-RISC 32-bit ruby </td><td> SHLIB_PATH                            </td></tr>
+  <tr><td> HP-UX PA-RISC 64-bit ruby </td><td> LD_LIBRARY_PATH                       </td></tr>
+  <tr><td> HP-UX IA64                </td><td> LD_LIBRARY_PATH                       </td></tr>
+  <tr><td> Mac OS X                  </td><td> DYLD_LIBRARY_PATH                     </td></tr>
+  <tr><td> AIX                       </td><td> LIBPATH                               </td></tr>
+</tbody>
+</table>
+
+For example:
+    $ LD_LIBRARY_PATH=/opt/oracle/instantclient_10_2
+    $ export LD_LIBRARY_PATH
+
+Linux rpm packages
+------------------
+
+Install the downloaded packages as follows:
+
+    rpm -i path/to/oracle-instantclient-basic-VERSION-ARCH.rpm
+    rpm -i path/to/oracle-instantclient-devel-VERSION-ARCH.rpm
+    rpm -i path/to/oracle-instantclient-sqlplus-VERSION-ARCH.rpm
+
+Set LD_LIBRARY_PATH to point to the directory where libclntsh.so is installed.
+
+For example:
+    $ LD_LIBRARY_PATH=/usr/lib/oracle/10.2.0.3/client/lib
+    $ export LD_LIBRARY_PATH
+
+Windows
+-------
+
+Unzip the packages and set PATH to point to the directory where OCI.DLL is installed.
+
+Check the environment
+=====================
+
+Oracle installation
+-------------------
+
+Run the following command and confirm it works fine. If it doesn't
+work well, check LD\_LIBRARY\_PATH or PATH.
+
+    sqlplus USERNAME/PASSWORD
+
+ruby installation
+-----------------
+
+Run the following command. If it ends with "can't find header files
+for ruby" or "ruby: no such file to load -- mkmf (LoadError)", you need
+to install ruby-devel(redhat) or ruby-dev(debian/ubuntu).
+
+    ruby -r mkmf -e ""
+
+development tools
+-----------------
+
+You need a C compiler and development tools such as make or nmake.
+Note that they must be same with ones used to compile the ruby.
+For example, you need Oracle Solaris Studio, not gcc, for ruby
+compiled by Oracle Solaris Studio.
+
+Installation
+============
+
+If you get a problem in the following steps, look at {file:docs/platform-specific-issues.md}
+and {file:docs/report-installation-issue.md}.
+
+gem package
+-----------
+
+Run the following command.
+
+    gem install ruby-oci8
+
+If you get a problem, look at {file:docs/platform-specific-issues.md}
+and {file:docs/report-installation-issue.md}.
+
+tar.gz package
+--------------
+
+### Download the source code
+
+Download the latest tar.gz package such as ruby-oci8 2.1.0.tar.gz,
+which is the latest version at the time of writing, from [rubyforge][].
+
+Note: if you are using Windows and you have no special need to compile
+it by yourself, look at {file:docs/install-binary-packge.md}.
+
+### Run make and install
+
+#### UNIX or Windows(mingw32, cygwin)
+
+    gzip -dc ruby-oci8-VERSION.tar.gz | tar xvf -
+    cd ruby-oci8-VERSION
+    make
+    make install
+
+note: If you use '`sudo`', use it only when running '`make install`'.
+'`sudo`' doesn't pass library search path to the executing command for security reasons.
+
+#### Windows(mswin32)
+
+
+    gzip -dc ruby-oci8-VERSION.tar.gz | tar xvf -
+    cd ruby-oci8-VERSION
+    nmake
+    nmake install
+
+[rubyforge]: http://rubyforge.org/frs/?group_id=256

Added: trunk/ruby-oci8/docs/platform-specific-issues.md
===================================================================
--- trunk/ruby-oci8/docs/platform-specific-issues.md	                        (rev 0)
+++ trunk/ruby-oci8/docs/platform-specific-issues.md	2012-03-11 11:59:32 UTC (rev 496)
@@ -0,0 +1,208 @@
+# @title Platform Specific Issues
+
+Linux
+=====
+
+Ubuntu 11.10 (Oneiric Ocelot)
+-----------------------------
+
+If the following error occurs even though libc6-dev is installed,
+
+  Do you install glibc-devel(redhat) or libc6-dev(debian)?
+  You need /usr/include/sys/types.h to compile ruby-oci8.
+
+You need to use ruby-oci8 2.1.0 or upper. Otherwise, run the following command and re-install ruby-oci8.
+
+ $ sudo ln -s /usr/include/linux/ /usr/include/sys
+
+General Linux
+-------------
+
+Use the same bit-width of libraries with ruby. For example, x86\_64
+instant client for x86\_64 ruby and 32-bit instant client for 32-bit
+ruby. It depends on the ruby but not on the OS. As for full client,
+x86\_64 ruby cannot use with 32-bit full client, but 32-bit ruby can
+use with 64-bit full client because 32-bit libraries are in
+$ORACLE\_HOME/lib32.
+
+To check which type of ruby do you use:
+
+    file `which ruby`
+
+Note: "`" is a back quote.
+
+Mac OS X
+========
+
+OS X 10.7 Lion
+--------------
+
+64-bit instant client doesn't work. Use 32-bit instant client or jruby.
+
+See:
+* http://rubyforge.org/forum/forum.php?thread_id=49548&forum_id=1078
+* https://forums.oracle.com/forums/thread.jspa?threadID=2187558
+
+Intel Mac (64-bit)
+------------------
+
+See [How to setup Ruby and Oracle Instant Client on Snow Leopard](http://blog.rayapps.com/2009/09/06/how-to-setup-ruby-and-oracle-instant-client-on-snow-leopard/).
+Note that setting the environment variable RC\_ARCHS=x86\_64 instead of ARCHFLAGS="-arch x86\_64" will work fine also.
+
+Intel Mac (32-bit)
+------------------
+
+See [How to setup Ruby and Oracle Instant Client on Snow Leopard](http://blog.rayapps.com/2009/09/06/how-to-setup-ruby-and-oracle-instant-client-on-snow-leopard/). Note that you need to replace x86\_64 with i386 in the blog.
+
+The Intel Instant client is for Mac OS X 10.5 Leopard. If you are using 10.4 Tiger,
+use one of the following workarounds.
+
+* compile ruby as ppc. (look at [How to setup Ruby and Oracle client on Intel Mac](http://blog.rayapps.com/2007/08/27/how-to-setup-ruby-and-oracle-client-on-intel-mac/))
+* use [ruby-odbc|http://www.ch-werner.de/rubyodbc/] and a third party ODBC driver ([Actual Technologies](http://www.actualtechnologies.com) or [OpenLink Software](http://uda.openlinksw.com/)).
+* use JRuby and Oracle JDBC driver.
+
+PowerPC Mac
+-----------
+
+See [How to setup Ruby and Oracle Instant Client on Snow Leopard](http://blog.rayapps.com/2009/09/06/how-to-setup-ruby-and-oracle-instant-client-on-snow-leopard/). Note that you need to replace x86\_64 with ppc in the blog.
+
+Solaris
+=======
+
+You need a same compiler which is used to make ruby itself.
+
+There are two ruby packages.
+
+* [Sunfreeware.com](http://www.sunfreeware.com/)
+* [Blastwave.org](http://www.blastwave.org/)
+
+The former is compiled by gcc. The latter is compiled by
+[Sun Studio](http://developers.sun.com/sunstudio/).
+The both compilers are freely available.
+
+If you use Blastwave.org's ruby and want not to install Sun Studio,
+you can edit rbconfig.rb by your self. [(look at here)](http://forum.textdrive.com/viewtopic.php?id=12630)
+
+If you use Sunfreeware.com's ruby and 
+
+    $ ruby -r rbconfig -e "p Config::CONFIG['GNU_LD']"
+
+prints "yes", you may need to edit rbconfig.rb distributed with the ruby
+as follows:
+
+   from: CONFIG["LDFLAGS"] = "-L.  -Wl,-E"
+   to:   CONFIG["LDFLAGS"] = "-L. "
+
+FreeBSD
+=======
+
+There are two ways.
+
+* use ruby and instant client on linux emulator
+* use oracle8-client port
+
+linux emulator
+--------------
+
+I have not run ruby-oci8 on linux emulator, but I guess it will
+run as follows. If it works, please tell me.
+
+If FreeBSD has a cross-compiler which can generate linux binaries,
+use it to compile ruby and ruby-oci8.
+
+If FreeBSD doesn't have such a compiler, install a linux distribution
+which FreeBSD can emulate to a PC machine, make ruby and ruby-oci8 in
+the linux box and copy them to the FreeBSD box as follows.
+
+On linux:
+
+    # make ruby
+    tar xvfz ruby-1.8.x.tar.gz
+    cd ruby-1.8.x
+    ./configure --prefix=/usr/local/ruby-1.8.x --enable-pthread
+    make
+    make install
+    # setup instant client
+      ....
+    # make ruby-oci8
+    PATH=/usr/local/ruby-1.8.x/bin:$PATH
+    tar xvfz ruby-oci8-1.0.x.tar.gz
+    cd ruby-oci8-1.0.x
+    make
+    make install
+    cd /usr/local/
+    tar cvfz ruby-1.8.x-linux.tar.gz ruby-1.8.x
+ 
+Copy ruby-1.8.x-linux.tar.gz to the FreeBSD box.
+ 
+On freebsd:
+
+    cd /compat/linux/usr/local
+    tar xvfz ruby-1.8.x-linux.tar.gz
+
+oracle8-client port
+-------------------
+
+I don't recommend this because of the following two reasons.
+
+* The oracle8-client port is made from Oracle 8.1.7.1 static library for Linux. Oracle have not supported the connectivity between 8.1.7.1 and Oracle 10g.
+* It is very unstable. When it fails to connect to an Oracle server, it is down by segmentation fault on FreeBSD 7.0 not only when using ruby-oci8, but also by a very simple test code written by C.
+
+If you try to use oracle8-client port, compile and install as follows.
+
+* install oracle8-client
+
+    cd /usr/ports/databases/oracle8-client
+    make
+    make install
+
+* set an environment variable ORACLE\_HOME
+
+    export ORACLE_HOME=/usr/local/oracle8-client
+
+The rest steps are described at {file:docs/install-full-client.md}.
+
+note: You have no need to set LD\_LIBRARY\_PATH because 
+Oracle libraries in oracle8-client port are static ones.
+
+HP-UX
+=====
+
+You need a ruby which is linked with ''libpthread'' and ''libcl''.
+
+Run `configure`.
+
+    tar xvfz ruby-1.9.x.tar.gz
+    cd ruby-1.9.x
+    ./configure
+
+Then open `Makefile` to add '-lpthread -lcl' to `LIBS` and run `make`
+and `make install`.
+
+    make
+    make install
+
+The rest steps are described at {file:docs/install-full-client.md}.
+
+Windows
+=======
+
+On some machines using a slow disk, you may get the following error.
+
+    Permission denied - conftest.exe
+
+Edit mkmf.rb for a workaround.
+
+    def try_run(src, opt="")
+      if try_link0(src, opt)
+        xsystem("./conftest")
+      else
+        nil
+      end
+    ensure
+      # add the following one line.
+      sleep 1 if /mswin32|cygwin|mingw32|bccwin32/ =~ RUBY_PLATFORM
+      rm_f "conftest*"
+    end
+
+See also: {http://abstractplain.net/blog/?p=788}.



More information about the ruby-oci8-commit mailing list