sventon subversion web client -
[show recent changes]
Rev: 8118 - svn:// / freehep / cvs / web / trunk / aidajni / ReleaseNotes-3.2.5.xhtml
Show File - ReleaseNotes-3.2.5.xhtml  [show properties]
Search for Help
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<meta name="GENERATOR" content="Microsoft FrontPage 6.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<title>Release Notes</title>
10  <body>
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="">here</a>.<br>
16  Release notes for all versions of AIDAJNI are available
17  <a href="">here</a>.</font></p>
18  <p>AIDAJNI is a C++ adapter of <a href="">AIDA - 
19  Abstract Interfaces for Data Analysis</a> which connects to a Java 
20  implementation of AIDA, such as <a href="">JAIDA</a>.</p>
21  <p>AIDAJNI allows C++ programmers to use any Java AIDA implementation. </p>
22  <p>It allows for instance <a href="">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="">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>
79  <p><font size="2">For a full list of changes in AIDAJNI 3.2.5 see the
80  <a href="">AIDAJNI
81  change log</a>.<br>
82  For a full list of changes in  AIDA 3.2.1 see the
83  <a href="">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="">AIDA 
91    3.2.1 Users' Guide</a></li>
92    <li><a href="">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="">FreeHEP Java Library</a> 
97  an &quot;Open Source&quot; library distributed under the terms of the
98  <a href="">LGPL</a>. If you have 
99  questions about the licensing please send a mail to:
100  <a href=""></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="">JAIDA</a>.</p>
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>
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 or .tar.gz file from 
119  the <a href=""></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`
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>
150  <h2><a name="Geant4">Using AIDAJNI from Geant4</a></h2>
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>
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>
160  <p><b>IMPORTANT</b>: Make sure you do <b>not</b> link in OPENGL libraries since they pre-load
161, 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="">4638291</a></p>
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    &quot;correct&quot; 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="">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="">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> is not implemented because we would need an ostream connected to 
224    an</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="">AIDA forum</a>. To 
235  report bugs or request enhancements you can also use the
236  <a href="">AIDAJNI bug database</a>.
237  </p>
238  <h2><a name="Examples">Examples</a></h2>
239  <p>The AIDJNI/examples directory contains 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 into an executable. JAIDA and AIDAJNI must have been set up before 
242  running the build script. </p>
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>
249  </body>
251  </html>

feed icon

sventon 2.5.1