incubator-kato-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From monte...@apache.org
Subject svn commit: r893178 - in /incubator/kato/trunk/org.apache.kato: kato.distro/src/main/readme/README kato.native.distro/src/main/assembly/nativebin.xml kato.native.distro/src/main/readme/ kato.native.distro/src/main/readme/README-native.txt
Date Tue, 22 Dec 2009 14:25:48 GMT
Author: monteith
Date: Tue Dec 22 14:25:47 2009
New Revision: 893178

URL: http://svn.apache.org/viewvc?rev=893178&view=rev
Log:
Add separate readme for native distribution.

Added:
    incubator/kato/trunk/org.apache.kato/kato.native.distro/src/main/readme/
    incubator/kato/trunk/org.apache.kato/kato.native.distro/src/main/readme/README-native.txt
Modified:
    incubator/kato/trunk/org.apache.kato/kato.distro/src/main/readme/README
    incubator/kato/trunk/org.apache.kato/kato.native.distro/src/main/assembly/nativebin.xml

Modified: incubator/kato/trunk/org.apache.kato/kato.distro/src/main/readme/README
URL: http://svn.apache.org/viewvc/incubator/kato/trunk/org.apache.kato/kato.distro/src/main/readme/README?rev=893178&r1=893177&r2=893178&view=diff
==============================================================================
--- incubator/kato/trunk/org.apache.kato/kato.distro/src/main/readme/README (original)
+++ incubator/kato/trunk/org.apache.kato/kato.distro/src/main/readme/README Tue Dec 22 14:25:47
2009
@@ -28,56 +28,22 @@
     3. Generate dump.
     4. Run tool that uses API to analyze dump.
 
-CJVMTI
-======
+Native Libraries
+================
 
-The CJVMTI agent allows the JVM to produce dumps that contain more information
-about the state of the JVM than hprof. 
-
-To start the JVM with the agent, pass the following option to the "java" command,
-or equivalent:
-
-    -agentpath:lib/cjvmti-linux-x86-${project.version}=s,r
-    -agentlib:cjvmti-linux-x86-${project.version}=s,r
-
-Where "s" is the number of stack frames that should be stored. Only those frames
-will be scanned for heap roots.
-"r" is the depth into the object graph the agent will store references from.
-"0" should be passed as "s" or "r" if they should be are unlimited, which is the default.
-
-For example:
-
-    -agentlib:cjvmti-windows-x86-${project.version}=3,4
-
-Will, on Windows, store the top three stack frames and will scan all objects up to
-4 references deep from those stack frames.
-
-With a stack trace like so:
-    Object.wait(long, int)
-    ReferenceQueue.wait(long)
-    ReferenceQueue.remove(long)
-    ReferenceQueue.remove()
-    Disposer.run()
-    Thread.run()
-
-Only the following stack traces would appear:
-    Object.wait(long, int)
-    ReferenceQueue.wait(long)
-    ReferenceQueue.remove(long)
-
-If there was a linked list in ReferenceQueue:
-    ALinkedList list;
-
-As the agent will only (in this case) scan objects 4 deep into the object graph,
-only the 3rd object into the list would be incorporated into the dump.
-
-e.g. ReferenceQueue -> ALinkedList -> Node -> Node -> Node 
-
-Limitations
------------
-
-. if local variable information is not available (JIT frames, no local variable info in class),
-  the variables won't appear in the debugger. Heap objects may be missing as a result.
+While most of this project is written in Java, there are two components
+that are compiled into platform specfic code. They are the Java JVMTI agent
+(CJVMTI) that generates a dump of the JVM state and a JNI library that provides
+a method of initiating a dump (hprof or JVMTI) without user intervention.
+
+The libraries are package separately in the following packages:
+
+    apache-kato-${project.version}-native-bin-linux-i386.tar.gz
+    apache-kato-${project.version}-native-bin-windows-x86.zip
+
+They can be unpackaged on top of this package. The libraries appear under 
+the lib directory.
+Please see their in README-native.txt .
 
 Dump API
 ========

Modified: incubator/kato/trunk/org.apache.kato/kato.native.distro/src/main/assembly/nativebin.xml
URL: http://svn.apache.org/viewvc/incubator/kato/trunk/org.apache.kato/kato.native.distro/src/main/assembly/nativebin.xml?rev=893178&r1=893177&r2=893178&view=diff
==============================================================================
--- incubator/kato/trunk/org.apache.kato/kato.native.distro/src/main/assembly/nativebin.xml
(original)
+++ incubator/kato/trunk/org.apache.kato/kato.native.distro/src/main/assembly/nativebin.xml
Tue Dec 22 14:25:47 2009
@@ -32,6 +32,7 @@
     <fileSet>
       <directory>src/main/readme/</directory>
       <outputDirectory>/</outputDirectory>
+      <filtered>true</filtered>
     </fileSet>
 
     <!--
@@ -59,6 +60,7 @@
       <outputDirectory>lib</outputDirectory>
       <unpack>false</unpack>
       <scope>compile</scope>
+      <fileMode>755</fileMode>
     </dependencySet>
 
   </dependencySets>

Added: incubator/kato/trunk/org.apache.kato/kato.native.distro/src/main/readme/README-native.txt
URL: http://svn.apache.org/viewvc/incubator/kato/trunk/org.apache.kato/kato.native.distro/src/main/readme/README-native.txt?rev=893178&view=auto
==============================================================================
--- incubator/kato/trunk/org.apache.kato/kato.native.distro/src/main/readme/README-native.txt
(added)
+++ incubator/kato/trunk/org.apache.kato/kato.native.distro/src/main/readme/README-native.txt
Tue Dec 22 14:25:47 2009
@@ -0,0 +1,84 @@
+Apache Kato ${project.version} - Native libraries
+=================================================
+
+This file explains how to use the native libraries used with Apache Kato.
+
+
+Overview
+========
+
+Apache Kato supplies the following libraries:
+
+    . A JVMTI agent for enabling Java Virtual Machines to produce rich
+      dumps (CJVMTI)
+    . A JNI library and Java API for causing hprof or CJVMTI dumps to be generated
+      programmatically.
+
+They are compiled for x86 Windows and Linux.
+
+CJVMTI
+======
+
+The CJVMTI agent allows the JVM to produce dumps that contain more information
+about the state of the JVM than hprof. 
+
+To start the JVM with the agent, pass the following option to the "java" command,
+or equivalent:
+
+    -agentpath:lib/cjvmti-linux-x86-${project.version}=s,r
+    -agentlib:cjvmti-linux-x86-${project.version}=s,r
+
+Where "s" is the number of stack frames that should be stored. Only those frames
+will be scanned for heap roots.
+"r" is the depth into the object graph the agent will store references from.
+"0" should be passed as "s" or "r" if they should be are unlimited, which is the default.
+
+For example:
+
+    -agentlib:cjvmti-windows-x86-${project.version}=3,4
+
+Will, on Windows, store the top three stack frames and will scan all objects up to
+4 references deep from those stack frames.
+
+With a stack trace like so:
+    Object.wait(long, int)
+    ReferenceQueue.wait(long)
+    ReferenceQueue.remove(long)
+    ReferenceQueue.remove()
+    Disposer.run()
+    Thread.run()
+
+Only the following stack traces would appear:
+    Object.wait(long, int)
+    ReferenceQueue.wait(long)
+    ReferenceQueue.remove(long)
+
+If there was a linked list in ReferenceQueue:
+    ALinkedList list;
+
+As the agent will only (in this case) scan objects 4 deep into the object graph,
+only the 3rd object into the list would be incorporated into the dump.
+
+e.g. ReferenceQueue -> ALinkedList -> Node -> Node -> Node 
+
+Limitations
+-----------
+
+. if local variable information is not available (JIT frames, no local variable info in class),
+  the variables won't appear in the debugger. Heap objects may be missing as a result.
+
+Kato VM API Implementation
+===========================
+
+Normally dumps are triggered by the Sun JVMs on error conditions or by a manual keypress.
+For example, ctrl+break on windows or ctrl+\ on Linux.
+In order to allow dumps to be generated programatically, this package supplies a native
+library that provides a native method that signals the JVM to generate a dump. 
+
+The library is called:
+    On Linux:   lib/libkatovmapi-linux-x86-${project.version}.so
+    On Windows: lib\katovmapi-windowx-x86-$project.version}.dll
+
+The lib directory should be on the LD_LIBRARY path or java.library.path property in order
+for it to be successfully loaded.
+



Mime
View raw message