svn commit: r881341 - in /incubator/kato/trunk/org.apache.kato: BUILDING README USING

[mo...@apache.org]

Author: monteith
Date: Tue Nov 17 15:44:48 2009
New Revision: 881341

URL: http://svn.apache.org/viewvc?rev=881341&view=rev
Log:
Add explanitory text files, which are a work in progress.

Added:
    incubator/kato/trunk/org.apache.kato/BUILDING
    incubator/kato/trunk/org.apache.kato/README
    incubator/kato/trunk/org.apache.kato/USING

Added: incubator/kato/trunk/org.apache.kato/BUILDING
URL: http://svn.apache.org/viewvc/incubator/kato/trunk/org.apache.kato/BUILDING?rev=881341&view=auto
==============================================================================
--- incubator/kato/trunk/org.apache.kato/BUILDING (added)
+++ incubator/kato/trunk/org.apache.kato/BUILDING Tue Nov 17 15:44:48 2009
@@ -0,0 +1,36 @@
+Building Apache Kato
+====================
+
+Apache Kato needs Maven 2.0 or above and a Java 6.0 JDK.
+To build the native libraries on Linux, GCC will have
+to be installed. Please consult your distribution's installation
+on how to do so.
+
+For the native libraries to be built on Windows, Microsoft's
+Visual C++ will have to be installed.
+
+Maven can be downloaded from:
+    http://maven.apache.org/download.html
+
+Sun's JDK 6.0 can be downloaded from:
+    http://java.sun.com/javase/downloads/index.jsp
+
+Other JDK's should also be sufficient.
+
+To build the jar files and documentation, go into the base directory and type:
+    mvn install
+
+
+The native libraries are not built as part of the main build. To do so, first
+the JAVA_HOME variable must be set to your install JDK location. 
+On Windows the "vcvars32.bat" script must be run before maven is launched.
+To start the build, simply run "mvn install" in the "kato.native" directory.
+
+Packaging
+=========
+
+Packaged binaries and source files are built by running:
+    mvn assembly:assembly
+
+in the kato.distro and kato.native.distro directories.
+

Added: incubator/kato/trunk/org.apache.kato/README
URL: http://svn.apache.org/viewvc/incubator/kato/trunk/org.apache.kato/README?rev=881341&view=auto
==============================================================================
--- incubator/kato/trunk/org.apache.kato/README (added)
+++ incubator/kato/trunk/org.apache.kato/README Tue Nov 17 15:44:48 2009
@@ -0,0 +1,53 @@
+Apache Kato M1 Release November 2009
+=====================================
+
+This is the milestone 1 release of the Apache Kato project.
+The Apache Kato project provides implementations of the JSR-326
+API which provides means of generating dumps in Java virtual machines
+and reading them. 
+
+The project currently provides the following:
+  
+    . An implementation of JSR-326 for accesing hprof files.
+    . A JVMTI agent (Windows and Linux x86) for providing dump files.
+    . An implementation of JSR-326 for accessing the JVMTI dumps.
+    . JNI library (Windows and Linux x86) for generating dumps on demand.
+    . An interactive command line tool for analyzing dumps.
+    . A JDI server for allowing Java debuggers to attach to dumps.
+    . JavaDoc for the API
+    . A PDF of the specification.
+
+Our website is here:
+    http://incubator.apache.org/kato
+
+To make queries regarding the API, please email:
+    kato-spec@incubator.apache.org
+Archive:
+    http://mail-archives.apache.org/mod_mbox/incubator-kato-spec/
+
+Other queries should be made to the following list:
+    kato-spec@incubator.apache.org
+Archive:
+    http://mail-archives.apache.org/mod_mbox/incubator-kato-dev/
+
+For instructions on how to build the project, see "BUILDING".
+For instructions on howto use the project, see "USING".
+
+ 
+Apache Kato welcomes your participation, whether it be code, testing,
+documentation or your design ideas.
+
+Many thanks,
+    The Apache Kato team.
+
+
+CHANGES
+=======
+
+M1-incubator November 2009
+==========================
+
+Initial release.
+
+
+

Added: incubator/kato/trunk/org.apache.kato/USING
URL: http://svn.apache.org/viewvc/incubator/kato/trunk/org.apache.kato/USING?rev=881341&view=auto
==============================================================================
--- incubator/kato/trunk/org.apache.kato/USING (added)
+++ incubator/kato/trunk/org.apache.kato/USING Tue Nov 17 15:44:48 2009
@@ -0,0 +1,72 @@
+Apache Kato ${project.version}
+==============================
+
+This file explains how to use the various subprojects that constitute
+Apache Kato. 
+
+The API
+=======
+
+The Apache Kato API is the JSR-326 API for accessing JVM dump artifacts. 
+This API allows Java programs to access the contents of dumps from JVMs.
+Currently there are two implementations of the API in Apache Kato, one
+reads hprof dumps from the Sun JVM and the hprof JVMTI agent, and the 
+other reads dumps generated by the JVMTI agent "CJVMTI", which is
+in the kato.native/kato.native.cjvmti project.
+
+API Documentation
+-----------------
+
+The API documentation can be found in the directory:
+     kato-${project.version}/docs 
+
+Under the directory are:
+    spec.pdf - This is the JSR-326 specification. It describes the structure
+               of the API, has examples of how to use it and also contains
+               the JavaDoc.
+
+    kato.api-${project.version}-javadoc.jar -
+               This jar contains the API's JavaDoc. Unjar it into a directory
+               and open the index.html file in a web browser to read it.
+
+The kato.tools.katoview and the kato.jdi projects are provided as examples of
+how to call the API. Their source can be found in the apache-kato-${project.version}-src.tar.gz
+and .zip packages.
+
+
+API Jars
+--------
+
+All of the jars and libraries are supplied under the "lib" directory.
+The Kato API classes and interfaces are needed to use any implementation
+of the API. They are needed to compile programs that use the API. They
+are available here:
+    lib/kato.api-${project.version}.jar
+
+Implementations of the API are expected to register themselves with the API,
+so it is important that the jar files containing them are put onto the JVM's
+classpath in the form they are provided. 
+
+The hprof implementation requires the following two libraries: 
+    lib/kato.hprof.api-${project.version}.jar
+    lib/kato.hprof.reader-${project.version}.jar
+
+
+lib/kato.cjvmti-${project.version}.jar
+
+
+
+Installing agent libraries.
+Generating dumps.
+    VM api, ctrl + break.
+
+The API, and specification.
+
+Using kato view.
+
+Using HProf
+=============
+
+Using the JDI server
+====================
+