From 516010d6e5f3d9fa0fae610c1f6594852a1e8994 Mon Sep 17 00:00:00 2001 From: Adam Dickmeiss Date: Thu, 21 May 2015 15:36:32 +0200 Subject: [PATCH] Added section on deployment + compilation on generic Unix --- doc/README.md | 82 +++++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 56 insertions(+), 26 deletions(-) diff --git a/doc/README.md b/doc/README.md index 5b6256f..49a54cd 100644 --- a/doc/README.md +++ b/doc/README.md @@ -3,10 +3,9 @@ INTRODUCTION Yaz4j is a Java binding for the high-level, client-side portion of the YAZ toolkit known as the ZOOM API. With Yaz4j you can program clients for YAZ- -supported protocols like z3950, SRU/W and SOLR. Yaz4j includes a native +supported protocols like Z39.50, SRU/W and Solr. Yaz4j includes a native component and supports Windows, Linux and OSX. - INSTALLATION ============ @@ -39,7 +38,7 @@ With the above repository enabled, yaz4j can be simply installed with: yum install yaz4j And the installation can be verified by running a provided test program which -executes a search against a public Index Data z3950 test server: +executes a search against a public Index Data Z39.50 test server: java -jar /usr/share/java/yaz4j.jar @@ -74,8 +73,8 @@ e.g: git checkout v1.5 -b v1.5 -Linux (e.g CentOS) ------------------- +Compilation on CentOS/RHEL +-------------------------- Compilation requires [JDK][1], [Maven][2], [Swig][3] and [YAZ][4] development packages installed. @@ -100,11 +99,11 @@ installed with: in which case Maven program is called `mvn-id` rather than `mvn`. With all dependencies in place you can continue the yaz4j compilation with: - + cd yaz4j mvn install -Which will also run tests that open a connection to Index Data's public z3950 +Which will also run tests that open a connection to Index Data's public Z39.50 server. Notice that `yaz-config` binary must be on the PATH (this is assured when @@ -116,11 +115,26 @@ installation is used, the binary location can be specified with: The compiled jar file ends up in any/target/yaz4j.jar while the native library in unix/target/libyaz4j.so. +Compilation on generic Unix +--------------------------- + +You will need the JDK, Maven, Swig and YAZ development packages. +Consult your package manager on how to install those. + +If yaz-config is in your PATH, the following command should suffice: + + mvn install + +If yaz-config is not in your PATH, you'll have to tell where YAZ is located: + + mvn -Dyaz.config=/path/to/yaz-config install + Windows ------- -Besides the exact same requirements as in the Unix case (JDK, Maven, Swig, YAZ), you will need the Windows [SDK][5] installed (which in turn requires .NET -Framework 4) to compile yaz4j. Again it's much easier to use the +Besides the exact same requirements as in the Unix case (JDK, Maven, Swig, +YAZ), you will need the Windows [SDK][5] installed (which in turn requires +.NET Framework 4) to compile yaz4j. Again it's much easier to use the YAZ Installer. Git must be installed to checkout yaz4j source code. Use the command prompt provided with the Windows SDK, navigate to the yaz4j @@ -128,9 +142,9 @@ source directory and run: mvn install -Default 64-bit YAZ installer location is assumed for the 'yaz.path' property. -Nothing is assumed for 'swig', so you either need to specify an absolute path -or update the PATH environment to include the directory containing swig.exe. +Default 64-bit YAZ installer location is assumed for the 'yaz.path' property. +Nothing is assumed for 'swig', so you either need to specify an absolute path +or update the PATH environment to include the directory containing swig.exe. Both can be specified with: mvn -Dyaz.path=/path/to/yaz/installdir -Dswig=/path/to/swig/binary install @@ -138,8 +152,8 @@ Both can be specified with: YAZ4J AND A SERVLET CONTAINER ============================= -If you are coding a web application that uses yaz4j there's a couple of things -to keep in mind. First, you are not invoking the JVM directly, but the servlet +If you are coding a web application that uses yaz4j there's a couple of things +to keep in mind. First, you are not invoking the JVM directly, but the servlet container (e.g Tomcat) run/init script is doing that for you and that's the place to configure any environment settings (e.g the PATH). Second, yaz4j includes static initializers to load the native part and can't be packaged along with the @@ -154,23 +168,23 @@ set up the default RPM-provided Tomcat 6 with yaz4j automatically: Linux (CentOS) -------------- -In case when yaz4j is installed through the RPM (Index Data's YUM repo) the -native libraries are placed in the standard system locations (/usr/lib/.. etc) +In case when yaz4j is installed through the RPM (Index Data's YUM repo) the +native libraries are placed in the standard system locations (/usr/lib/.. etc) and are readily available to all applications, including Tomcat. The only other thing to configure is to add yaz4j.jar (the pure Java component) to Tomcat's common class loader (further down). In case when yaz4j is built from source or for some other reason the native -pars are not present in the standard system library locations, they need to be -placed on the servlet container's shared libraries load path. One way -to do this in Tomcat (assuming Tomcat is run from a tarball rather than RPM) is +pars are not present in the standard system library locations, they need to be +placed on the servlet container's shared libraries load path. One way +to do this in Tomcat (assuming Tomcat is run from a tarball rather than RPM) is by editing (create it if it does not exist) the CATALINA_HOME/bin/setenv.sh` script and putting the following lines in there: LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/libyaz4j.so export LD_LIBRARY_PATH -Notice, that this has to be done for all native libraries that `yaz4j.so` +Notice, that this has to be done for all native libraries that `yaz4j.so` dependson, e.g `libyaz5.so` and so on, unless they are already on the default s ystem library paths (e.g when installed from RPMs). @@ -182,14 +196,14 @@ it becomes available to all deployed webapps and is loaded only once. There are a couple ways to do that. One (employed by `yaz4j-tomcat6` RPM) is to place (or symlink) `yaz4j.jar` to -to `$CATALINA_BASE/lib` (CATALINA_BASE is `/usr/share/tomcat6` when Tomcat was +to `$CATALINA_BASE/lib` (CATALINA_BASE is `/usr/share/tomcat6` when Tomcat was installed from RPMs on CentOS): ln -s /path/to/yaz4j.jar /usr/share/tomcat6/lib and restart Tomcat. -Another option is to edit the file `catalina.properties` shipped with Tomcat +Another option is to edit the file `catalina.properties` shipped with Tomcat (and located in `CATALINA_BASE/conf/` e.g `/etc/tomcat6/`on RPM-packaged Tomcat) and extend the `common.loader=` property with the following: @@ -203,12 +217,12 @@ Windows ------- On Windows Tomcat will most likely be run from the binary distribution which -includes `CATALINA_BASE/bin/setenv.sh` for the purpose of setting up the +includes `CATALINA_BASE/bin/setenv.bat` for the purpose of setting up the environment. Unless, you have installed yaz4j.dll with the YAZ Installer and -checked the option to update the global PATH and include all native YAZ and y -az4j components, edit setenv.sh with the following: +checked the option to update the global PATH and include all native YAZ and +yaz4j components, edit setenv.bat with the following: - set PATH=%PATH;X:\path\to\yaz\bin;X:\path\to\yaz4j.dll + set PATH=%PATH;X:\path\to\yaz\bin;X:\path\to\yaz4j.dll The `X:\path\to\yaz\bin` is `C:\Program Files\YAZ\bin` when the installer was used and includes also yaz4j.dll. @@ -220,6 +234,22 @@ To deploy `yaz4j.jar` you must follow steps identical to those from the Linux section. Again, when installer is used `yaz4j.jar` is located at `C:\Program Files\YAZ\java\yaz4j.jar`. +Deploy a test app +----------------- + +Under yaz4j/examples you'll find a small zgate app. This can be deployed +to Tomcat to test the yaz4j installation. To do so: + + cd yaz4j/examples/zgate + mvn install + cp target/zgate.war CATALINA_BASE/webapps + +(substitute / with \\ and copy as necessary under Windows!) + +If successful you can run the application with a URL as follows: + +[http://localhost:8080/zgate/?zurl=z3950.indexdata.com/marc&query=computer&syntax=usmarc](http://localhost:8080/zgate/?zurl=z3950.indexdata.com/marc&query=computer&syntax=usmarc) + PREPARING A DEVELOPMENT ENVIRONMENT =================================== -- 1.7.10.4