<?php
include ("../links.php");
include ("../includes/header.html");
?>
<fieldset><h1>Compiling HDF-JAVA Source on Unix</h1></fieldset>
<p>
<h2>
Source Files</h2>
After you download and extract the source package, you will have the HDF Java
native C code and the Java source code for JNI, HDF-Object package and HDFView.
You need to compile the C source and Java source separately. The following
instructions tell you how to build the C source in Visual C++ and the Java
source from batch file.
<p>
<table WIDTH=100% BORDER COLS=2 bgcolor="#f4f4f4">
<caption><b>HDF Java Product Source</b></caption>
<tr>
<th> Source directory</th>
<th> Description</th>
</tr>
<tr>
<td> hdf-java/native/hdflib/</td>
<td> C header files and C source files for HDF4 Java Native Interface</td>
</tr>
<tr>
<td> hdf-java/native/hdf5lib/</td>
<td> C header files and C source files for HDF5 Java Native Interface</td>
</tr>
<tr>
<td> hdf-java/ncsa/hdf/hdflib/</td>
<td> Java source files for HDF4 Java Native Interface</td>
</tr>
<tr>
<td> hdf-java/ncsa/hdf/hdf5lib/</td>
<td> Java source files for HDF5 Java Native Interface</td>
</tr>
<tr>
<td> hdf-java/ncsa/hdf/object/</td>
<td> Java source files for HDF-Object package</td>
</tr>
<tr>
<td> hdf-java/ncsa/hdf/view/</td>
<td> Java source files for HDFView</td>
</tr>
</table>
<hr>
<h3>
Requirements</h3>
You need the following libraries in order to compile the HDF Java products.
<UL>
<LI>The Pre-Compiled HDF4 Binaries: obtain from
<a href="/release4/obtain.html">/release4/obtain.html</a>
<LI>The Pre-Compiled HDF5 Binaries: obtain from
<a href="/HDF5/release/obtain5.html">/HDF5/release/obtain5.html</a>
<LI> JPEG Library: obtain from
<a href="http://www.hdfgroup.org/ftp/lib-external/jpeg/">http://www.hdfgroup.org/ftp/lib-external/jpeg/</a>
<LI> GZIP Library: obtain from
<a href="http://www.hdfgroup.org/ftp/lib-external/zlib/">http://www.hdfgroup.org/ftp/lib-external/zlib/</a>
<LI> SZIP Library: obtain from
<a href="http://www.hdfgroup.org/ftp/lib-external/szip/">http://www.hdfgroup.org/ftp/lib-external/szip/</a>
<LI> JDK 1.5.0 or above
</UL>
<hr>
<h3>
Unix</h3>
The HDF Java products source includes configure and make files to build the
Java products. The source code includes the Java code for the HDF native
interface to HDF4 and HDF5, the ncsa.hdf.objects package, ncsa.hdf.io packages,
and the HDFView packages. HDF4 and HDF5 can be selected or deselected. The
source does not include the HDF4 or HDF5 libraries or any dependent libraries.<br>
<br>
To build from source requires a C compiler and a Java compiler, JDK1.5.x or
above. The autoconf and make files work with Gnu tools and gmake.<br>
<hr>
<h3>
Configure script</h3>
The first step is to run the configure script. The configure script checks
the dependent libraries and other requirements, and generates Makefiles.
<br>
<br>
The C code for the native interface requires the static HDF libraries and
the external filters for HDF. It is difficult to autodetect these libraries,
so the configure requires that the paths be specified. The configure script
checks and reports any missing libraries.<br>
<br>
The source distribution includes the file "runconfig_example.sh". This
file shows an example for how to set the paths and call configure. (<a href="#figx">Figure 1</a>). In many cases, this script can be edited to fill in the paths, and then used to configure.<br>
<br>
<br>
<table cellpadding="4" cellspacing="2" border="1" width="80%" align="center" bgcolor="#f4f4f4">
<tbody>
<tr>
<td valign="top">
#!/bin/sh<br>
<br>
## This is an example script to set the configure parameters for<br>
## the HDF Java products.<br>
##<br>
## The paths need to be set according to the local configuration<br>
##<br>
## May need to adjust the arguments to configure<br>
##<br>
##<br>
<br>
##<br>
## IMPORTANT NOTE: The make files require 'gmake'<br>
##<br>
## Be sure to 'setenv MAKE gmake' if necessary<br>
##<br>
<br>
<b>INSTDIR=
# FILL IN where to install the hdfview.<br>
<br>
JAVAINC=
# FILL IN path to java includes (jni.h, etc.)<br>
JAVALIB=
# FILL IN path to java lib (the rt.jar, etc.)<br>
<br>
HDF5=
# path to HDF5 installation, e.g., /usr/local/hdf5-1.6.2<br>
HDF4=
# path to HDF4 installation (if used)<br>
HDF45=
# path to HDF4 to HDF5 installation (if used)</b><br>
<br>
## Autoconf detects shared libraries, but we need static versions<br>
## must set these paths for external libraries needed for HDF libraries.<br>
<br>
# JPEG is required by HDF4. If HDF4 is used, _must_ set JPEG<br>
<b>JPEG=
# FILL IN path to JPEG installation (the path to libjpeg.a is needed)</b><br>
<br>
# GZIP is required by HDF4 and optional for HDF5. <br>
# If HDF4 is used, _must_ set GZIP<br>
# If HDF5 is used and zlib is used, _must_ set GZIP<br>
<b>GZIP=
# FILL IN path to GZIP installation (the path to libz.a is needed)</b><br>
<br>
# SZIP is optional for HDF4 and HDF5. <br>
# If szip is used in one or both HDF libraries, _must_ set SZIP<br>
<b>SZIP=
# FILL IN path to SZIP installation (the path to libsz.a is needed)</b><br>
<br>
####<br>
<br>
./configure --prefix=$INSTDIR --with-jdk=$JAVAINC,$JAVALIB \<br>
--with-hdf5=$HDF5/include,$HDF5/lib \<br>
--with-hdf4=$HDF4/include,$HDF4/lib \<br>
--with-libsz=$SZIP/include,$SZIP/lib \<br>
--with-libz=$GZIP/include,$GZIP/lib \<br>
--with-libjpeg=$JPEG/include,$JPEG/lib <br>
<br>
# other options<br>
# <br>
# --without-hdf4 -- omit HDF4<br>
# --without-hdf5 -- omit HDF5<br>
# --without-libsz -- omit SZIP<br>
# --without-libz -- omit GZIP<br>
# --without-libsz -- omit GZIP<br>
#<br>
<br>
#<br>
# Some options required only for macOSX<br>
# <br>
# -build=powerpc-apple <br>
# --with-jdkclasses=
# path to classes if not in 'jdk/lib'<br>
# --with-javabin=
# path to java bin, if not in 'jdk/bin'<br></pre>
<br>
</td>
</tr>
</tbody>
</table>
<div align="center"><b>Figure 1.</b><a name="figx"></a><br>
</div>
<hr>
<h3>
Build</h3>
After configure runs successfully, the source is build with 'make'. <br>
<br>
By default make builds all the Java classes and all the C code for the HDF4
and/or HDF5 library if selected. The Java classes are organized into six
jar files:<br>
<br>
<table cellpadding="2" cellspacing="2" border="1" width="80%" align="center" bgcolor="#f4f4f4">
<tbody>
<tr>
<td valign="top">
jhdf.jar<br>
</td>
<td valign="top">The Java interface to the HDF4 Library (requires libhdf.so)<br>
</td>
</tr>
<tr>
<td valign="top">jhdf5.jar<br>
</td>
<td valign="top">The Java interface to the HDF4 Library (requires libhdf5.so)<br>
</td>
</tr>
<tr>
<td valign="top">jhdfobj.jar<br>
</td>
<td valign="top">The Generic Data Object package (interfaces), ncsa.hdf.object (See <pointer>)<br>
</td>
</tr>
<tr>
<td valign="top">jhdf4obj.jar<br>
</td>
<td valign="top">The implementation of the object package for HDF4 (requires jhdf.jar)<br>
</td>
</tr>
<tr>
<td valign="top">jhdf5obj.jar<br>
</td>
<td valign="top">The implementation of the object package for HDF5 (requires jhdf5.jar)<br>
</td>
</tr>
<tr>
<td valign="top">jhdfview.jar<br>
</td>
<td valign="top">The Java GUI, requires all jars and C libs.<br>
</td>
</tr>
</tbody>
</table>
<br>
<br>
The C code is organized into two libraries:<br><br>
<table cellpadding="2" cellspacing="2" border="1" width="80%" align="center" bgcolor="#f4f4f4">
<tbody>
<tr>
<td valign="top">
libjhdf.so<br>
</td>
<td valign="top">The JNI wrapper for HDF4, plus the HDF4 library (implements native calls for jhdf.jar)<br>
</td>
</tr>
<tr>
<td valign="top">libjhdf5<br>
</td>
<td valign="top">The JNI wrapper for HDF45 plus the HDF4 library (implements native calls for jhdf5.jar)<br>
</td>
</tr>
</tbody>
</table>
<br>By default, the 'make' builds the C and Java code to create all the jars and libraries. <br>
<br>
Optionally, HDF4 or HDF5 may be omitted (--without-hdf4, --without-hdf5).
In this case, the corresponding library and jar files will not be built.<br>
<br>
The 'make install' installs the jar files and the C libraries in the directory specified by "--prefix" parameter in configure.<br>
<br>
See the Makefile for other options.<br>
<hr>
<h3>
Running the HDF Java code</h3>
<br>
The Java HDF has two parts, the Java classes and the C libraries. The Java
classes are executed with a Java VM, just as any Java classes. The C libraries
are loaded when the Java classes for the JNI are initialized. The C libraries
must be in the library search path for the JVM. <br>
<br>
Note that while the Java classes are the same for all platforms, there is a different C library for each platform.<br>
<br><a href="#fig2">
Figure 2</a> shows an example shell script for running the hdfview on linux.
The search paths are set, and then the program is invoked with the
correct paths. Other Unix systems, macosx, and windows would have similar
procedure, with details differing for each platform.<br>
<br>
<div align="center"><br>
</div>
<table cellpadding="4" cellspacing="2" border="1" width="80%" align="center" bgcolor="#f4f4f4">
<tbody>
<tr>
<td valign="top">
#!/bin/sh<br><br>
# where the HDFView is installed<br>
HDFVIEW_HOME=/programs/java/hdf<br>export HDFVIEW_HOME<br><br>
# where Java is installed (requires jdk1.5.0 or above)<br>
JAVAPATH=/opt/jdk1.5.0/bin<br>export JAVAPATH<br><br>
# all the jar files<br>CPATH=$HDFVIEW_HOME"/lib/jhdf.jar"<br>
CPATH=$CPATH":"$HDFVIEW_HOME"/lib/jhdf5.jar"<br>
CPATH=$CPATH":"$HDFVIEW_HOME"/lib/jhdfobj.jar"<br>
CPATH=$CPATH":"$HDFVIEW_HOME"/lib/jhdf4obj.jar"<br>
CPATH=$CPATH":"$HDFVIEW_HOME"/lib/jhdf5obj.jar"<br>
CPATH=$CPATH":"$HDFVIEW_HOME"/lib/jhdfview.jar"<br><br>
# Example: includes netcdf and fits support<br>
CPATH=$CPATH":""$HDFVIEW_HOME"/lib/netcdf.jar:"$HDFVIEW_HOME"/lib/fits.jar"<br><br><br>
if test -z "$CLASSPATH" ; then<br>
CLASSPATH=""<br>
fi<br>
CLASSPATH=$CPATH":"$CLASSPATH<br>
export CLASSPATH<br><br><br>
if test -n "$JAVAPATH" ; then<br>
PATH=$JAVAPATH":"$PATH<br>
export PATH<br>fi<br><br><br>
if test -z "$LD_LIBRARY_PATH" ; then<br>
LD_LIBRARY_PATH=""<br>
fi<br><br>
# example: set path for linux <br><br>
LD_LIBRARY_PATH=$HDFVIEW_HOME/lib/linux:$LD_LIBRARY_PATH<br>
export LD_LIBRARY_PATH<br><br><br>
$JAVAPATH/java -mx512m ncsa.hdf.view.HDFView -root $HDFVIEW_HOME<br><br>
</td>
</tr>
</tbody>
</table>
<p>
<div align="center"><b><a name="fig2"></a>Figure 2. Example shell script to launch the hdfview</b><br>
</div>
<br>
In order to use the JNI interfaces in other products, the jhdf.jar and/or
jhdf5.jar (HDF4, HDF5) archives must be in the class path for the Java compilation
and run time. The libjhdf.so and/or libjhdf5.so must be in the LD_LIBRARY_PATH
for running.<br>
<hr>
<h3>
Problems</h3>
The configure and make process has many dependencies, so it is prone to problems.<br>
<br>
First, compiling the C into the libjhdf and libhdf5 must use the correct
parameters to the C compiler. This depends on the Java Virtual Machine that
will be used, as well as the platform. The C code is very portable, but different
JVMs have different requirements for how to build loadable libraries. See
the documentation for your JVM.<br>
<br>
Second, there are many different versions of Java, some may not compile.
The HDF Java products have been tested with Sun's Java Development Kit 1.3.1
and 1.4.1. <br>
<br>
The most common problem is difficulty running the code after compilation.
This is usually caused by problems with the class path or library path. When
one of the jar files is missing from the class path, the program will encounter
a "Class not found" exception. A similar error will occur if the library
with the native implementation is not found in the LD_LIBRARY_PATH.<br>
<br>
The source distribution includes two small test programs that test the link
paths (using the install directory specified in the configure). These are
in the directory test/linktest. To check the installation, change to the
directory, type 'make'. The 'testlink' program runs the TestHDF5Link.java
program, and 'testlink4' runs TestHDF5Link.java. These Java program check
the loading and invokation of the HDF library. If the link test succeeds,
the paths in the script are correct for using the Java HDF products.<br>
<?php
include ("../includes/footer.html");
?>
