Merge lp:~zorba-coders/zorba/b1197577-macDocs into lp:zorba

[Cezar Andrei]

Add documentation on how to install Zorba and run examples in Python, PHP, Ruby and Java.

Add documentation on how to install Zorba and run examples in Python, PHP, Ruby and Java.

[Cezar Andrei (cezar-andrei)]

review: Approve

[lp:~zorba-coders/zorba/b1197577-macDocs]

11642. By Chris Hillery on 2013-10-14

Merge from trunk.

[Chris Hillery (ceejatec)]

review: Approve

[Zorba Build Bot (zorba-buildbot)]

Validation queue starting for the following merge proposals:
https://code.launchpad.net/~zorba-coders/zorba/b1197577-macDocs/+merge/188143

Progress dashboard at http://jenkins.lambda.nu/view/ValidationQueue

[Zorba Build Bot (zorba-buildbot)]

Validation queue succeeded - proposal merged!

=== modified file 'doc/zorba/indexpage.dox.in'
--- doc/zorba/indexpage.dox.in	2013-09-17 16:29:09 +0000
+++ doc/zorba/indexpage.dox.in	2013-10-14 22:35:48 +0000
@@ -15,6 +15,7 @@
   - \ref build
 
 \section install_section Install
+  - \ref install_osx_tutorial
   - \ref php_ubuntu_tutorial
   - \ref php_windows_tutorial
   - \ref python_windows_tutorial

=== added file 'doc/zorba/install_osx.dox'
--- doc/zorba/install_osx.dox	1970-01-01 00:00:00 +0000
+++ doc/zorba/install_osx.dox	2013-10-14 22:35:48 +0000
@@ -0,0 +1,237 @@
+/** \page install_osx_tutorial Zorba - Mac OSX Installation
+
+\section zosx_title Guide to Zorba installation on Mac OSX
+
+This is a guide to install Zorba on Mac OSX, it was tested on OSX 10.8.5 Mountain Lion with Xcode 5.0 and Zorba 2.9.1. Send us email with the results you had on different versions or platforms.
+
+There are 3 ways to get Zorba running on your Mac:
+  - \ref zosx_pkg (Requires macports dependencies, recommended)
+  - \ref zosx_mpkg (.mpkg file contains all it's .pkg dependencies, easiest)
+  - \ref zosx_src  (the most complete)
+
+\section zosx_prereq Prerequisites
+
+   - Apple Mac OSX 10.8.5 Mountain Lion
+   - Apple Xcode Developer Tools version 5.0 (might work with 4.4 or later too)
+   - For a) and c) MacPorts 2.2.0 (see below).
+   
+\section zosx_install_macports Install MacPorts
+
+Install MacPorts 2.2.0: <a href="http://www.macports.org/install.php">http://www.macports.org/install.php</a> . The easiest way to install MacPorts on a Mac OS X system is by downloading and running the .dmg file.
+
+Update MacPorts
+\code
+$ sudo port -v selfupdate
+\endcode
+
+Upgrade outdated packages (this might take a while depending on the outdated packages).
+
+\code
+$ sudo port upgrade outdated
+\endcode
+
+
+\section zosx_pkg a) Install Zorba binary from .pkg file
+
+The zorba-2.9.1.pkg file contains only Zorba installation files but not it's dependecies. Unlike Linux and Windows distributions, it contains both Zorba runtime with core modules and most of the external modules. It does not contain the folowing external modules: image, schema-tools, read-pdf and email, due to lack of macports of these modules dependencies. If one of these modules is required, then Zorba must be installed from source.
+
+Make sure you have MacPorts installed and up to date. Since .pkg contains only Zorba installation files, it's dependecies need to be installed too.
+
+Install dependecies:
+\code
+sudo port install boost curl icu libiconv libxml2 libxslt xerces3 tidy fop geos libarchive sqlite3 swig swig-python swig-php swig-java swig-ruby
+\endcode
+
+\b Note: Use MacPorts installation of the libraries, do not modify the libraries that ships with OSX. Modifying OXS libraries usualy renders your OSX installation unusable.
+
+Download the zorba .pkg file (aproximately 12MB) : <a href="http://launchpad.net/zorba/+download">zorba-x.pkg</a>.
+
+Install it by running it, a MacPorts gui installer will guide you.
+
+after installation Zorba binary should be available in: /opt/local/bin/zorba.
+
+To uninstall Zorba files, use the folowing script: <a href="http://my.zorba-xquery.com/tmp/zorba-2.9.1-uninstall.sh">zorba-2.9.1-uninstall.sh</a>.
+
+
+
+\section zosx_mpkg b) Install Zorba binary from .mpkg file
+
+This is the easies way to install Zorba since it doesn't require installation of MacPorts and requires download and installation of only one file.
+- The Zorba .mpkg file contains both the Zorba installation files and also all it's MacPorts dependecies. This makes the zorba-2.9.1.mpkg a 175MB file.
+- Similar to .pkg file, the .mpkg file contains the Zorba runtime, core modules and most of the external modules. It does not contain the folowing external modules: image, schema-tools, read-pdf and email, due to lack of macports of these modules dependencies. If one of these modules is required, then Zorba must be installed from source.
+
+Download the zorba .mpkg file (aproximately 175MB) : <a href="http://launchpad.net/zorba/+download">zorba-x.mpkg</a>.
+
+Install it by running it, a MacPorts gui installer will guide you.
+
+Zorba binary should be available in: /opt/local/bin/zorba
+
+To uninstall only Zorba files, use the following script: <a href="http://my.zorba-xquery.com/tmp/zorba-2.9.1-uninstall.sh">zorba-2.9.1-uninstall.sh</a>. For the rest of the packages use their own recommendations.
+
+
+
+
+\section zosx_src c) Install Zorba from sources
+This is the most flexible way of installing Zorba, one has access to all it's build configuration and has the opportunity to select the required external modules including the image, schema-tools and read-pdf.
+
+This requires instalation of < href="http://www.macports.org/install.php">MacPorts 2.2.0</a> and installation of Zorba dependecy ports:
+
+\code
+sudo port install boost curl icu libiconv libxml2 libxslt xerces3 tidy fop geos libarchive sqlite3 swig swig-python swig-php swig-java swig-ruby
+\endcode
+
+For more details on configuring and building Zorba from sources see: 
+  - \ref build
+  - or <a href="https://docs.google.com/document/d/14KD51yoT27sK-g4dn0YVSAnCbX8nPsDaF_Gsdi2oWdo/edit">Zachary Graceffa's guide</a>.
+
+\b Note: Make sure you don't have any binary Zorba versions instaled, if you do you need to uninstall them in order to have Zorba build correctly from your sources.
+
+
+
+\section zosx_python Working with Python
+
+The installer puts the Zorba python library in: /opt/local/share/python/, so this path needs to be added to system path. 
+
+The contents of test.py:
+
+\code
+import sys
+sys.path.insert(0, '/opt/local/share/python/')
+import zorba_api
+
+print "Running: Get zorba instance and shutdown"
+
+store = zorba_api.InMemoryStore_getInstance()
+zorba = zorba_api.Zorba_getInstance(store)
+zorba.shutdown()
+zorba_api.InMemoryStore_shutdown(store)
+
+print "Success"
+\endcode
+
+Since the installer is done by MacPorts, the MacPorts python needs to be used. To run the test python script use:
+
+\code
+/opt/local/bin/python2.7 test.py
+\endcode
+
+A list of other python examples can be found in <a href="http://bazaar.launchpad.net/~zorba-coders/zorba/trunk/files/head:/doc/python/examples/">doc/python/examples</a> and <a href="http://bazaar.launchpad.net/~zorba-coders/zorba/trunk/files/head:/swig/python/tests/">swig/python/tests/</a>.
+
+
+
+\section zosx_php Working with PHP
+
+The Zorba library for PHP is installed under: /opt/local/share/php5/. PHP needs a \b php.ini configuration file that has to contain:
+
+\code
+extension_dir=/opt/local/share/php5/
+include_path=/opt/local/share/php5/
+\endcode
+
+The test.php file should look like:
+\code
+<?
+require 'zorba_api_wrapper.php';
+
+print "Running: Get zorba instance and shutdown\n";
+
+$store = InMemoryStore::getInstance();
+$zorba = Zorba::getInstance($store);
+
+$zorba->shutdown();
+InMemoryStore::shutdown($store);
+
+print "Success";
+?>
+\endcode
+
+To run the script use:
+\code
+php -c path/to/php.ini/ test.php
+\endcode
+
+A list of other PHP examples can be found in <a href="http://bazaar.launchpad.net/~zorba-coders/zorba/trunk/files/head:/doc/php/examples/">doc/php/examples</a> and <a href="http://bazaar.launchpad.net/~zorba-coders/zorba/trunk/files/head:/swig/php/tests/">swig/php/tests/</a>.
+
+
+
+\section zosx_ruby Working with Ruby
+
+The Zorba library for Ruby is installed under /opt/local/share/ruby/zorba_api.bundle. 
+
+The test.rb file contains:
+
+\code
+require '/opt/local/share/ruby/zorba_api'
+
+print "Running: Get zorba instance and shutdown"
+
+store = Zorba_api::InMemoryStore.getInstance()
+zorba = Zorba_api::Zorba.getInstance(store)
+zorba.shutdown()
+Zorba_api::InMemoryStore.shutdown(store)
+
+print "Success"
+\endcode
+
+To run the script execute:
+
+\code
+ruby test.rb
+\endcode
+
+A list of other Ruby examples can be found in <a href="http://bazaar.launchpad.net/~zorba-coders/zorba/trunk/files/head:/doc/ruby/examples/">doc/ruby/examples</a> and <a href="http://bazaar.launchpad.net/~zorba-coders/zorba/trunk/files/head:/swig/ruby/tests/">swig/ruby/tests/</a>.
+
+
+
+\section zosx_java Working with Java
+
+To make Java work with Zorba, the Zorba library needs to be on the path and the Zorba jars need to be on the class path. Zorba library and jars are installed under /opt/local/share/java.
+
+\code
+export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/local/share/java
+export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:/opt/local/share/java
+export CLASSPATH=$CLASSPATH:/opt/local/share/java/zorba_api.jar:/opt/local/share/java/zorba_xqj.jar:/opt/local/share/java/xqjapi.jar
+\endcode
+
+Compile and run your files as usual:
+
+\code
+javac -cp $CLASSPATH Test.java
+java -cp $CLASSPATH:. Test
+\endcode
+
+A simple source on how to use it in code:
+
+\code
+import javax.xml.xquery.*;
+import org.zorbaxquery.api.xqj.*;
+
+class Test
+{
+   static
+   {
+     System.loadLibrary ( "zorba_api" );
+   }
+   
+   public static void main(String[] args) throws XQException
+   {
+     System.out.println("Test Zorba");
+             
+     ZorbaXQDataSource xqds = new ZorbaXQDataSource();
+     XQConnection xqc = xqds.getConnection();
+     XQExpression xqe = xqc.createExpression();
+     XQResultSequence result = xqe.executeQuery("1+2");
+
+     while (result.next()) {
+       // Print the current item in the sequence
+       System.out.println(">   " + result.getItemAsString(null));
+     }
+
+     xqc.close();
+   }        
+}
+\endcode
+ 
+A list of other Ruby examples can be found in <a href="http://bazaar.launchpad.net/~zorba-coders/zorba/trunk/files/head:/doc/xqj/examples/">doc/xqj/examples</a> and <a href="http://bazaar.launchpad.net/~zorba-coders/zorba/trunk/files/head:/swig/xqj/managers/">swig/xqj/managers/</a>.
+
+*/

=== modified file 'swig/ruby/CMakeLists.txt'
--- swig/ruby/CMakeLists.txt	2013-09-21 00:39:52 +0000
+++ swig/ruby/CMakeLists.txt	2013-10-14 22:35:48 +0000
@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 IF(APPLE)
-CMAKE_FIND_FRAMEWORKS ( Ruby )
+  CMAKE_FIND_FRAMEWORKS ( Ruby )
 ENDIF(APPLE)
 FIND_PACKAGE(Ruby)
 
@@ -33,10 +33,17 @@
     # apparently doesn't allow CMake's RPATH-rewriting magic to work.
     GET_TARGET_PROPERTY(_rpath zorba_simplestore LOCATION)
     GET_FILENAME_COMPONENT(_rpath "${_rpath}" PATH)
-    SET_TARGET_PROPERTIES(zorba_api PROPERTIES
-      INSTALL_RPATH "${CMAKE_INSTALL_RPATH}:${_rpath}"
-      BUILD_WITH_INSTALL_RPATH ON
-      OUTPUT_NAME "${ZORBA_SWIG_LIB_PREFIX}zorba_api")
+    IF (APPLE)
+      SET_TARGET_PROPERTIES(zorba_api PROPERTIES
+        INSTALL_RPATH "${CMAKE_INSTALL_RPATH}:${_rpath}"
+        BUILD_WITH_INSTALL_RPATH ON
+        OUTPUT_NAME "zorba_api")
+    ELSE (APPLE)
+      SET_TARGET_PROPERTIES(zorba_api PROPERTIES
+        INSTALL_RPATH "${CMAKE_INSTALL_RPATH}:${_rpath}"
+        BUILD_WITH_INSTALL_RPATH ON
+        OUTPUT_NAME "${ZORBA_SWIG_LIB_PREFIX}zorba_api")
+    ENDIF (APPLE)
   ENDIF (WIN32)
 
   IF ( APPLE )
@@ -60,7 +67,7 @@
   SET (RUBY_SITEARCH_DIR "${CMAKE_INSTALL_PREFIX}/share/ruby")
   
   IF ( APPLE )
-    INSTALL ( FILES ${CMAKE_CURRENT_BINARY_DIR}/${ZORBA_SWIG_LIB_PREFIX}zorba_api_ruby.bundle
+    INSTALL ( FILES ${CMAKE_CURRENT_BINARY_DIR}/zorba_api_ruby.bundle
     DESTINATION ${RUBY_SITEARCH_DIR} )
   ELSE ( APPLE )
     IF ( LINUX )