| 1 |
<html> |
| 2 |
|
| 3 |
<head> |
| 4 |
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> |
| 5 |
<meta name="GENERATOR" content="Microsoft FrontPage 6.0"> |
| 6 |
<meta name="ProgId" content="FrontPage.Editor.Document"> |
| 7 |
<title>Release Notes</title> |
| 8 |
</head> |
| 9 |
|
| 10 |
<body> |
| 11 |
|
| 12 |
<h1>AIDAJNI 3.2.5 Release Notes (NOT YET RELEASED)</h1> |
| 13 |
<p><font size="2">Release Notes Version: $Revision: 8118 $.</font></p> |
| 14 |
<p><font size="2">The most recent version of this file is available |
| 15 |
<a href="http://java.freehep.org/aidajni/ReleaseNotes-3.2.5.html">here</a>.<br> |
| 16 |
Release notes for all versions of AIDAJNI are available |
| 17 |
<a href="http://java.freehep.org/aidajni/AllReleaseNotes.html">here</a>.</font></p> |
| 18 |
<p>AIDAJNI is a C++ adapter of <a href="http://aida.freehep.org/">AIDA - |
| 19 |
Abstract Interfaces for Data Analysis</a> which connects to a Java |
| 20 |
implementation of AIDA, such as <a href="http://java.freehep.org/jaida">JAIDA</a>.</p> |
| 21 |
<p>AIDAJNI allows C++ programmers to use any Java AIDA implementation. </p> |
| 22 |
<p>It allows for instance <a href="http://geant4.cern.ch/geant4">Geant4</a>, written in |
| 23 |
C++, to create histograms and ntuples in Java and store them in .aida files, |
| 24 |
which can be analyzed using |
| 25 |
<a href="http://jas.freehep.org/jas3/index.html">JAS3 - Java Analysis Studio</a>.</p> |
| 26 |
<h2>Contents</h2> |
| 27 |
<ul> |
| 28 |
<li><a href="#Compliance">AIDA Compliance</a></li> |
| 29 |
<li><a href="#Platforms">Supported Platforms</a></li> |
| 30 |
<li><a href="#Changes">Major changes in AIDAJNI 3.2.5</a></li> |
| 31 |
<li><a href="#Documentation">Documentation</a></li> |
| 32 |
<li><a href="#License">License</a></li> |
| 33 |
<li><a href="#Installation">Installing AIDJNI</a></li> |
| 34 |
<li><a href="#Compilation">Compiling AIDAJNI</a></li> |
| 35 |
<li><a href="#Building">Building an Application with AIDAJNI</a></li> |
| 36 |
<li><a href="#Running">Running an Application with AIDAJNI</a></li> |
| 37 |
<li><a href="#Geant4">Using AIDAJNI from Geant4</a></li> |
| 38 |
<li><a href="#Features">Features/Limitations of the Current Release</a></li> |
| 39 |
<li><a href="#BugReporting">Reporting Bugs</a></li> |
| 40 |
<li><a href="#Examples">Examples</a></li> |
| 41 |
</ul> |
| 42 |
<h2><a name="Compliance">AIDA Compliance</a></h2> |
| 43 |
<p>This adapter connects AIDA-C++ to AIDA-JNI. It almost fully supports the AIDA |
| 44 |
standard. The C++ and Java side are both AIDA 3.2.1 compliant (for usage in Geant 4.6.x).</p> |
| 45 |
<h2><a name="Platforms">Supported Platforms</a></h2> |
| 46 |
<p>Binaries are available and supported for the following combinations of |
| 47 |
architectures and compilers:</p> |
| 48 |
<ul> |
| 49 |
<li>Windows NT/2000/XP<ul> |
| 50 |
<li><b>WIN32-VC7</b>: Visual Studio .NET Professional 2003.<br> |
| 51 |
Microsoft (R) 32-bit C/C++ Optimizing Compiler Version |
| 52 |
13.10.3077 for 80x86</li> |
| 53 |
<li><b>WIN32-g++</b>: gcc version 3.3.1 (cygming special)<br> |
| 54 |
Using a cygwin shell.</li> |
| 55 |
</ul> |
| 56 |
</li> |
| 57 |
<li>Linux Red Hat Linux 7.2 (Enigma) 2.4.20-30.7.legacysmp (2x1396MHz Intel)<ul> |
| 58 |
<li><b>Linux-g++2</b>: gcc version 2.95.3 20010315 (release)</li> |
| 59 |
</ul> |
| 60 |
</li> |
| 61 |
<li>RHEL WS 3 (Taroon Update 1) 2.4.21-15.0.4.ELsmp (2x1396MHz Intel)<ul> |
| 62 |
<li><b>Linux-g++</b>: gcc version 3.2.3 20030502 (Red Hat Linux 3.2.3-24)</li> |
| 63 |
<li><b>Linux-icc</b>: Intel(R) C++ Compiler for 32-bit applications, |
| 64 |
Version 8.0 Build 20031231Z Package ID: l_cc_pc_8.0.058</li> |
| 65 |
<li><b>Linuxamd64-g++</b> <i>(supported only)</i>: gcc version 3.4.2 |
| 66 |
20041017 (Red Hat 3.4.2-6.fc3)</li> |
| 67 |
</ul></li> |
| 68 |
<li>MacOS X 10.3<ul> |
| 69 |
<li><b>Darwin-g++</b>: gcc version 3.3 20030304 (Apple Computer, Inc. build 1666)</li> |
| 70 |
</ul> |
| 71 |
</li> |
| 72 |
<li>SUN Solaris<ul> |
| 73 |
<li><b>SUN-CC</b>: CC: Forte Developer 7 C++ 5.4 Patch 111715-13 2003/12/11</li> |
| 74 |
</ul> |
| 75 |
</li> |
| 76 |
</ul> |
| 77 |
<h2><a name="Changes">Major changes in AIDAJNI 3.2.5</a></h2> |
| 78 |
|
| 79 |
<p><font size="2">For a full list of changes in AIDAJNI 3.2.5 see the |
| 80 |
<a href="http://java.freehep.org/redirect?project=AIDAJNI&area=bugs&report=changelog">AIDAJNI |
| 81 |
change log</a>.<br> |
| 82 |
For a full list of changes in AIDA 3.2.1 see the |
| 83 |
<a href="http://aida.freehep.org/releaseNotes.thtml">AIDA change |
| 84 |
log</a>.</font></p> |
| 85 |
<h2><a name="Documentation">Documentation</a></h2> |
| 86 |
<p>These release notes list issues specific to the AIDAJNI implementation of AIDA. |
| 87 |
In general all of the AIDA documentation applies to AIDAJNI, in particular the |
| 88 |
following are useful:</p> |
| 89 |
<ul> |
| 90 |
<li><a href="http://aida.freehep.org/doc/v3.2.1/UsersGuide.html">AIDA |
| 91 |
3.2.1 Users' Guide</a></li> |
| 92 |
<li><a href="http://aida.freehep.org/doc/v3.2.1/api/index.html">AIDA 3.2.1 API |
| 93 |
documentation</a></li> |
| 94 |
</ul> |
| 95 |
<h2><a name="License">License</a></h2> |
| 96 |
<p>AIDAJNI is part of the <a href="http://java.freehep.org/">FreeHEP Java Library</a> |
| 97 |
an "Open Source" library distributed under the terms of the |
| 98 |
<a href="http://www.gnu.org/copyleft/lesser.html">LGPL</a>. If you have |
| 99 |
questions about the licensing please send a mail to: |
| 100 |
<a href="mailto:developers@freehep.org">developers@freehep.org</a>.</p> |
| 101 |
<h2><a name="Installation">Installin</a>g AIDAJNI</h2> |
| 102 |
<p>Download and install a Java AIDA Implementation which supports AIDA 3.2.1, for |
| 103 |
example <a href="http://java.freehep.org/jaida">JAIDA</a>.</p> |
| 104 |
|
| 105 |
<p>Download AIDAJNI for one or more platforms. These distributions overlay on |
| 106 |
top of each other, adding support for different architectures. The distribution |
| 107 |
creates the following directory structure:</p> |
| 108 |
|
| 109 |
<pre>AIDAJNI-version containing license and release notes |
| 110 |
AIDAJNI-version/bin containing platform specific directories with setup scripts |
| 111 |
AIDAJNI-version/examples containing examples |
| 112 |
AIDAJNI-version/include containing all necessary include files |
| 113 |
AIDAJNI-version/lib containing platform specific directories with libraries |
| 114 |
(shareable and static)</pre> |
| 115 |
<h2><a name="Compilation">Compilation</a></h2> |
| 116 |
<p>The current distributions do not contain source files. </p> |
| 117 |
<p>To (re-)build AIDAJNI for a |
| 118 |
particular platform you need to get AIDAJNI-3.2.5-src.zip or .tar.gz file from |
| 119 |
the <a href="ftp://ftp.slac.stanford.edu/software/freehep/AIDAJNI/v3.2.5/">ftp://ftp.slac.stanford.edu/software/freehep/AIDAJNI/v3.2.5/</a> directory. </p> |
| 120 |
<p>Follow the instructions in README-src.html contained in that |
| 121 |
distribution.</p> |
| 122 |
<h2><a name="Building">Building</a> an Application with AIDAJNI</h2> |
| 123 |
<p>Set the environment variable AIDAJNI_HOME to your unpacked AIDAJNI |
| 124 |
distribution. Make sure JDK_HOME is set to your Java Development Kit (1.4 or |
| 125 |
better), and source the system specific aidajni-setup file (.sh/.csh fro Unix, |
| 126 |
.bat for Windows, .win32 for Cygwin).</p> |
| 127 |
<p>Example for Linux-g++, using tcsh:</p> |
| 128 |
<blockquote> |
| 129 |
<pre>setenv AIDAJNI_HOME /users/tom/AIDAJNI-3.2.5 |
| 130 |
setenv JDK_HOME /users/tom/j2sdk1.4.1 |
| 131 |
source $AIDAJNI_HOME/bin/Linux-g++/aidajni-setup.csh</pre> |
| 132 |
</blockquote> |
| 133 |
<p>Now you are able to execute the aida-config utility:</p> |
| 134 |
<blockquote> |
| 135 |
<pre>aida-config --version will display the version you installed. |
| 136 |
aida-config --include will display the include options |
| 137 |
for your compiler. |
| 138 |
aida-config --lib will display the library link options |
| 139 |
for your linker.</pre> |
| 140 |
</blockquote> |
| 141 |
<p>To compile (example for Linux-g++): </p> |
| 142 |
<blockquote> |
| 143 |
<pre>g++ -c `aida-config --include` YourApplication.cc |
| 144 |
g++ YourApplication.o `aida-config --lib`</pre> |
| 145 |
</blockquote> |
| 146 |
<h2><a name="Running">Running</a> an Application with AIDAJNI</h2> |
| 147 |
<p>Once you have run the aidajni-setup script successfully you can just execute |
| 148 |
your application.</p> |
| 149 |
|
| 150 |
<h2><a name="Geant4">Using AIDAJNI from Geant4</a></h2> |
| 151 |
|
| 152 |
<p>For <b>Geant4 version 4.5.x</b> use AIDAJNI 3.0.4 and its Geant4 overlay |
| 153 |
product. See <a href="ReleaseNotes-3.0.4.html">ReleaseNotes</a> of version |
| 154 |
3.0.4.</p> |
| 155 |
|
| 156 |
<p>For <b>Geant4 version 4.6.x</b> the fixes to the A01 example and the overlay |
| 157 |
are included in the Geant4 release. One only needs to install JAIDA and AIDAJNI |
| 158 |
as described above.</p> |
| 159 |
|
| 160 |
<p><b>IMPORTANT</b>: Make sure you do <b>not</b> link in OPENGL libraries since they pre-load |
| 161 |
libXt.so, which will make the JavaVM crash when it tries to open its first Window/Frame. |
| 162 |
This does NOT apply to the Windows Operating System of course. This bug was |
| 163 |
reported to Sun Microsystems as early as JDK 1.3.1, and has not been fixed for |
| 164 |
JDK 1.5. |
| 165 |
Bugnumber <a href="http://developer.java.sun.com/developer/bugParade/bugs/4638291.html">4638291</a></p> |
| 166 |
|
| 167 |
<h2><a name="Features">Features/Limitations of the Current Release</a></h2> |
| 168 |
<p>The following limitations exist:</p> |
| 169 |
<ul> |
| 170 |
<li>On MacOS X there are some complications running the GUI parts of AIDAJNI |
| 171 |
(Plotter, ...). The problem is that non-bundled applications on MacOS X, such |
| 172 |
as AIDAJNI, cannot by default interact with the user or open any GUI windows. |
| 173 |
To overcome this problem there are a number of undocumented (Apple) calls one |
| 174 |
can do. However it also turns out that one needs to also start Java in the |
| 175 |
"correct" thread. This all is undocumented by Apple, so there is no easy |
| 176 |
programmatic way out. Our solution is the following:<ul> |
| 177 |
<li>If you only use the non-GUI parts of AIDAJNI, there should be no |
| 178 |
problems and you can just compile, link and run your program with AIDAJNI.</li> |
| 179 |
<li>If you use the GUI parts of AIDAJNI we run your C++ program from Java. |
| 180 |
This makes sure that the Apple JavaVM will be initialized correctly, on the |
| 181 |
right thread and as a GUI application. When your program calls AIDAJNI, we |
| 182 |
will search (and find) the JavaVM which was already started and use that to |
| 183 |
handle calls to JAIDA. To do so, you application should not be linked into |
| 184 |
an executable but into a shared library with a statement similar to the |
| 185 |
following:<br> |
| 186 |
<font face="Courier New" size="2"><br> |
| 187 |
g++ -dynamiclib -flatnamespace -o libYourApplicationName.jnilib $AIDAJNI_HOME/lib/Darwin-g++/runs.o |
| 188 |
...</font><br> |
| 189 |
<br> |
| 190 |
You then need to set up the DYLD_LIBRARY_PATH to point to this shared |
| 191 |
library:<br> |
| 192 |
<br> |
| 193 |
<font face="Courier New" size="2">export DYLD_LIBRARY_PATH=/usr/home/duns/YourApplicationsDirectory:$DYLD_LIBRARY_PATH</font><br> |
| 194 |
<br> |
| 195 |
And can then start you application with the command:<br> |
| 196 |
<br> |
| 197 |
<font face="Courier New" size="2">java runs YourApplicationName<br> |
| 198 |
</font><i><br> |
| 199 |
runs.class implements the small java wrapper around your application.</i><br> |
| 200 |
<br> |
| 201 |
In future releases of MacOS X this problem may be fixed by apple and this |
| 202 |
solution will not be needed anymore.<br> |
| 203 |
For more information see |
| 204 |
<a href="http://bugs.freehep.org/secure/ViewIssue.jspa?id=11386">AIDAJNI-28</a>.</li> |
| 205 |
</ul> |
| 206 |
</li> |
| 207 |
<li>On Linux RedHat 9 distribution a program using AIDAJNI will finish with a |
| 208 |
crash, due to some threading problem in the Linux kernel. You need to set |
| 209 |
LD_ASSUME_KERNEL 2.4.1 to avoid this crash, until the next kernel is |
| 210 |
distributed. For more information see |
| 211 |
<a href="http://bugs.freehep.org/secure/ViewIssue.jspa?key=AIDAJNI-5">AIDAJNI-5</a> in our bug database.</li> |
| 212 |
<li>There may be memory leaks in some places, but we currently cannot run AIDAJNI through valgrind, since valgrind core dumps on running the Java |
| 213 |
Virtual Machine.</li> |
| 214 |
<li>Many routines will return references to objects which are ONLY valid until |
| 215 |
the next |
| 216 |
call to the same routine is made.</li> |
| 217 |
<li>CIxxx.cpp and CIxxx.h classes are currently available for experimental use |
| 218 |
only. They allow a C++ implementation of an object (Histogram for instance) to |
| 219 |
be passed to and handled by Java. This allows a C++ histogram |
| 220 |
to be plotted by a Java plotter. Current concrete CI classes do <b>NOT</b> |
| 221 |
include: <b>CIAnalysisFactory, CIDataPointSetFactory and CIHistogramFactory</b>. Only classes for which CI classes |
| 222 |
exist can be passed from C++ to Java.</li> |
| 223 |
<li>ITree.ls() is not implemented because we would need an ostream connected to |
| 224 |
an java.io.OutputStream.</li> |
| 225 |
<li>ITuple.fill on ITupleEntry is implemented but will not work.</li> |
| 226 |
<li>ITuple.getObject() will fail if the stored column is not an ITuple.</li> |
| 227 |
<li>ITree.listObjectNames() and ITree.listObjectTypes() return an empty list |
| 228 |
in case of failure.</li> |
| 229 |
<li>The distribution kits contain some CVS directories and files, please |
| 230 |
ignore.</li> |
| 231 |
</ul> |
| 232 |
<h2><a name="BugReporting">Reporting Bugs</a></h2> |
| 233 |
<p>For discussion of features or problems related to AIDAJNI please use the |
| 234 |
<a href="http://java.freehep.org/redirect?project=AIDAJNI&area=forum">AIDA forum</a>. To |
| 235 |
report bugs or request enhancements you can also use the |
| 236 |
<a href="http://java.freehep.org/redirect?project=AIDAJNI&area=bugs&report=changelog">AIDAJNI bug database</a>. |
| 237 |
</p> |
| 238 |
<h2><a name="Examples">Examples</a></h2> |
| 239 |
<p>The AIDJNI/examples directory contains AidaTest.cc which serves as a small test as well as an example. |
| 240 |
The subdirectories g++, CC and VC contain build scripts to compile and link |
| 241 |
AidaTest.cc into an executable. JAIDA and AIDAJNI must have been set up before |
| 242 |
running the build script. </p> |
| 243 |
|
| 244 |
<p>The standard AIDATest package in C++ is |
| 245 |
used to test the AIDAJNI adapter. Some minor tweaks are being made to the tests |
| 246 |
and the JAIDA implementation so that all of them will pass, but we believe the AIDAJNI does not |
| 247 |
have major errors in it.</p> |
| 248 |
|
| 249 |
</body> |
| 250 |
|
| 251 |
</html> |
