Added: incubator/harmony/enhanced/trunk/sandbox/contribs/bootjvm/bootJVM/README
URL: http://svn.apache.org/viewcvs/incubator/harmony/enhanced/trunk/sandbox/contribs/bootjvm/bootJVM/README?rev=307257&view=auto
==============================================================================
--- incubator/harmony/enhanced/trunk/sandbox/contribs/bootjvm/bootJVM/README (added)
+++ incubator/harmony/enhanced/trunk/sandbox/contribs/bootjvm/bootJVM/README Fri Oct  7 21:27:56 2005
@@ -0,0 +1,1567 @@
+#!
+# @file ./README
+#
+# @brief Introductory annotations.
+#
+# @section Control
+#
+# \$URL: https://svn.apache.org/path/name/README $ \$Id: README 0 09/28/05 dlydick $
+#
+# Copyright 2005 The Apache Software Foundation
+# or its licensors, as applicable.
+# 
+# Licensed under the Apache License, Version 2.0 ("the License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# 
+#     http://www.apache.org/licenses/LICENSE-2.0
+# 
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+# either express or implied.
+# 
+# See the License for the specific language governing permissions
+# and limitations under the License.
+#
+#
+# @version \$LastChangedRevision: 0 $
+#
+# @date \$LastChangedDate: 09/28/2005 $
+#
+# @author \$LastChangedBy: dlydick $
+#         Original code contributed by Daniel Lydick on 09/28/2005.
+#
+#
+# @section Reference
+#
+# @see LICENSE
+#
+# @see INSTALL
+#
+# @note:   (In the following narratives, the normal documentation tags
+#          are @e not used so that this file may be used in a
+#          stand-alone fashion without the assistance of any document
+#          reader and without knowledge of such tags.)
+#
+# @note:   See also the documentation page named "Main Page" for an
+#          overview from the JVM spec section number perspective.
+#
+# @todo Need to verify which web document for the
+#       Java 5 class file definition is either "official",
+#       actually correct, or is the <em>de facto</em> standard.
+#
+# @verbatim
+
+
+Apache Harmony Bootstrap Java Virtual Machine
+=============================================
+
+This implementation of the Java Virtual Machine has been written
+as a (notice "a", not "the") reference implementation that comprises
+almost all of the facilities of a JVM without any further changes.
+
+Please see the file named 'INSTALL' in this same directory for
+instructions on installing and building the program.
+
+
+The goals of this effort are:
+
+  (1) To provide a working Java Virtual Machine interpreter to the
+      Apache Harmony project as a cornerstone for a Java runtime
+      environment, especially considering the possibility of using
+      it as a bootstrap JVM in the final project code base, where
+      and if applicable.
+
+  (2) To provide a working Java Virtual Machine to the Apache Harmony
+      project as a starting point for architectural discussions
+      to help the project get started in earnest, pulling itself
+      up "by its bootstraps," as it were.  Thus a second reason to
+      call this project the "bootstrap JVM."     :-|   :-O  :-)
+
+  (3) To provide a highly modular implementation so pieces may be added
+      and modified and removed with minimal impact to other pieces.
+      For example, the heap allocation component may be easily
+      switched between three modes, 'simple' and 'bimodal' and 'other'.
+      This is accomplished by running 'config.sh' and changing it
+      there.  In like manner, the garbage collection component or any
+      future component so constructed may be easily replaced without
+      any changes to other code.  Other components may not be _quite_
+      as hermetically sealed, such as the class file loader or threading
+      mechanism, but the structure is present to improve upon the
+      implementations, as desired.
+
+  (4) To provide a simple code implementation written in straight,
+      vanilla ANSI 'C' using the ubiquitous GCC compiler so that the
+      code may be easily and efficiently adapted and modified to perform
+      all tasks without esoteric tools, and utilizing the experience
+      and creativity of _all_ contributors.  The only suggestion is
+      that each contributor working on source code learn how to use
+      Doxygen, a simple, powerful, and highly configurable C/C++
+      documentation utility. There is an abundance of example commentary
+      in the showing how to use it for a wide variety of project
+      documentation purposes.  Furthermore, its installation also
+      includes extensive built-in documentation about itself.
+
+  (5) To provide a very clear and concise code base for teaching JVM
+      concepts to potential contributors.
+
+  (6) To organize the code as a simple static library that can be linked
+      into any larger body of code, and also to be able to connect JNI
+      shared object files/dynamic load libraries to it easily.
+
+  (7) To provide a sample main() program entry point for how to link
+      and use the static library.
+
+  (8) To provide a start on the native side of the JNI implementation
+      of java.lang.* and java.io.* (etc.) that may be more fully
+      fleshed out by project contributors as a way to start becoming
+      familiar with the core code.  Also to provide a similar start on
+      the JNI side for the same reasons, including a sample main()
+      program there.
+
+This implementation is NOT intended to be:
+
+  (1) The final Apache Harmony JVM.
+
+  (2) The authority or standard against which JVM's are measured,
+      whether by the Apache Harmony project or otherwise.
+
+  (3) The most efficient possible implementation.  Issues of
+      modularity, concise implementation, and ease of understanding
+      how the code works take precedence over runtime efficiency
+      issues, including CPU time, memory resources, and the like.
+
+This contribution consists of about 52,000 lines of 'C', Java, shell
+scripts, and data files.  It has been written, unit tested, and
+_lightly_ integration tested.  It is being contributed partly with
+testing in mind to familiarize contributors with the code as they
+work with it and continue with integration testing, especially while
+extending its feature set into a full-fledged, bullet-proof
+work of art.  This file contains a list of items that should be
+addressed, both features and bug fixes.  Furthermore, the source
+code and therefore the pre-formatted documentation contains over
+200 focused, specific enhancements, questions, and problems in
+the @todo list that should be addressed during this process.
+
+It is my hope that this contribution will be the seed that helps the
+Apache Harmony project to sprout, mature, and bloom into a first-class
+Java Virtual Machine that is worthy of the reputation of the
+Apache brand.
+
+
+Yours Truly
+
+
+
+Daniel Lydick
+September 28, 2005
+
+
+
+---
+
+
+Configuration
+-------------
+Run the 'config.sh' script in this directory to configure for
+your environment.  It creates a './config' sub-directory with
+a './config/config.h' header file containing top-level compile
+parameters. This file is always referenced in every source file
+of the core JVM code by including "arch.h".  This script also
+creates other files there useful with the 'build.sh' scripts
+and contains normal compiler command line parameters.  Eclipse
+project files are also available which contain these same
+compile command line parameters.
+
+Whatever Java JDK you are currently using is probably fine for
+now when running this JVM.  Reading of JAR files is _not_ done via
+the JAR classes (yet), but with your '$JAVA_HOME/bin/jar' utility.
+The test classes may be compiled with your JDK's '$JAVA_HOME/bin/javac'
+compiler.  All this is in an attempt to leverage the functionality
+of your existing JDK to "bootstrap" this bootstrap JVM into existence.
+Eventually, of course, all this will get replaced with Harmony
+versions of all of these components.  A seed for these components
+is found in the Java classes in 'jni/src/harmony/generic/0.0'.
+Currently, these classes contain _only_ definitions for what is
+termed "local native methods".  These are JNI method calls to
+code that has intimate knowledge of the details of the JVM
+implementation, such as 'java.lang.Object.wait()'.  (See
+'jvm/src/native.c' for more information.)
+
+Once the 'config.sh' completes successfully, run 'build.sh' in any
+or all directories where it is found to build that diretctory or
+directory tree.  At the top level, 'build.sh all' will build the
+entire project.  Call it as 'build.sh help' for options.
+
+Eclipse project files are provided to do the same things with the
+same options except that it does not compile the Java classes in
+'jni/src/harmony/generic/0.0'.  (Notice that if you change
+anything, it will need to be changed for both 'build.sh' and for
+Eclipse if you want them be both work the same.)  The original
+development of this code was on a Sun Ultra 5 with Solaris 9
+running GCC 3.3.2, Gmake 3.80, GNU binutils 2.11.2, and GDB 6.0,
+coordinated under Eclipse 3.0.2 with the C/C++ plugin CDT 2.1.1.
+The JDK was Sun's 1.4.2_06-b03.  The source code was documented
+with Doxygen 1.4.4, Solaris version.
+
+
+Code organization
+-----------------
+(The following description is also found in 'jvm/src/jni'c for
+display on the "Main Page" documentation.)
+Several directories are provided within the source tree:
+
+   jvm        Source code for JVM, including a main() wrapper.
+              Builds binary file 'jvm/bin/bootjvm'.
+
+   libjvm     For building 'jvm' as a statically linked
+              library archive, less main() wrapper.  Builds
+              library archive 'libjvm/lib/libjvm.a'.  Source
+              code comes from the 'jvm' directory.
+
+   main       A simple main() wrapper that links
+              'libjvm/lib/libjvm.a' and builds binary
+              file 'main/bin/bootjvm'.  Source code comes
+              from the 'jvm' directory.
+
+   jni        Source code for a sample JNI shared library
+              'jni/harmony/generic/0.0/lib/bootjni.so'
+              for linking with JNI code, but needs the
+              build directives to be functional, as it
+              currently links statically with a main() into
+              a binary just like 'jvm'.  This directory
+              contains a tree for JNI implementations from any
+              supplier that wants to support the Harmony project.
+              Currently, there is one JNI implementation here,
+              found in 'jni/src/harmony/generic/0.0'.
+
+   test       Builds numerous Java test classes in 'test/bin'
+              for driving development work.
+
+With the exception of the Java test classes in 'test/src',
+all source code is found in 'jvm/src' and in the directory tree
+'jni/src/vendor/product/version'.  The purpose of 'libjvm'
+and 'main' for demonstrating various possible organizations
+for the source code, namely for building a static library archive
+and for linking it.
+
+The source code is about 3 MB in size.  The final size of all of
+parts of the compiled code tree is about 12 MB.  The full
+documentation tree in 'doc.ORIG' is about another 55 MB when fully
+installed.  It may be removed if desired in favor of maintaining
+_only_ the working documentation in 'doc' as generated by 'build.sh dox'
+at the top level, which will be the same size as 'doc.ORIG' if all
+documentation formats are desired, or less if fewer documentation
+formats are used.  For example, if only the HTML format is used,
+the 'doc' directory will be about 19 MB in size.
+
+Comments in the source will _always_ mention 'C' language "functions",
+but Java language "methods", and _never_ the reverse.  This is part
+of an attempt to separate the two compile and runtime domains.  See
+also comments on this subject below under 'jrtypes.h' and the source
+itself for additional comments about type definitions in the Java
+and real machine domains.
+
+Subsystem component abstraction
+-------------------------------
+The implementation key Java concepts is performed in the following
+source files with corresponding navigation macros:
+
+    Component        Source and header       Navigation
+    ---------        -----------------       ----------
+    Java class       class.[ch]              CLASS() macro
+                     classutil.c
+
+    Java object      object.[ch]             OBJECT() macro
+                     objectutil.c
+
+    Java thread      thread.[ch]             THREAD() macro
+                     threadstate.c
+                     threadutil.c
+
+    Java method      method.[ch]             METHOD() macro
+
+    Java class       field.[ch]              FIELD() macro
+    static field,
+    object instance
+    
+
+    JVM registers    jvmreg.h                STACK(), et al
+
+    Java native      native.[ch]             --
+                     jlObject.[ch]           --
+                     jlClass.[ch]            --
+                     jlString.[ch]           --
+                     jlThread.[ch]           --
+
+    JVM spec
+      class file     classfile.[ch]          Many, see cfmacros.h
+
+    Heap modules     heap.h                  HEAP_xxx() macros
+                     heap_simple.c
+                     heap_bimodal.c
+
+    Garbage          gc.h                    GC_xxx() macros
+    collection       gc_stub.c
+    modules
+
+
+
+By simply changing out the respective source file and adjusting
+the main navigation macro for that component, the implementation
+can be changed drastically without affecting the other components.
+(Larger implementations will have more than one source file, see
+especially 'threadstate.c'.)  It is _highly_ unlikely that the
+'classfile.[ch]' components will _ever_ change since this is under
+the direct control of the Java specification, but the others are
+under the control of this project and may be modified to suit its
+needs as desired.
+
+
+Support Scripts
+===============
+Following is a short description of each script file and other
+support files:
+
+config.sh  <---  * * *   START HERE AFTER READING 'INSTALL' FILE   * * *
+---------
+Introduce users to the project and how to set it up and configure it
+for various CPU platforms and for various functional features.
+This interactive shell script provides introductory material and
+a description of which versions of which software tools are needed
+to compile and document the project and how to administer the
+pre-formatted documentation.
+
+It then starts evaluating the existing Java JDK (as declared by the
+JAVA_HOME environment variable) for existence of the proper tools and
+verifies the name of the class library archive that will be used for
+temporary access to JVM startup classes such as the root object
+java.lang.Object.class .
+
+Once this introductory evaluation is complete, it will ask questions
+about how to configure the project for compile, runtime, and
+distribution features, as well as which components to build and
+to document.  Once the questions are answered, the project is
+configured and optionally built using 'build.sh cfg'.
+
+build.sh
+clean.sh
+common.sh
+---------
+Top-level build scripts that invokes build scripts of the same names
+at the various levels in the directory tree.  The one named 'build.sh'
+compiles the source code, while the one named 'clean.sh' removes the
+effects of that build.  The shared file 'common.sh' is used by both
+of these scripts.  Notice that nowhere in the tree except here at the
+top level will the documentation build occur, as it is a global process
+due to interdependencies of @link and @see directives, among others.
+
+getsvndata.sh
+getsvndups.sh
+-------------
+Show a list of all revisions of all source files compiled into an
+object file, a library archive, or a linked binary with 'getsvndata.sh'.
+Show a list of conflicting revisions using 'getsvndups.sh'.  Object
+files may not have conflicts, neither may library archives.  Linked
+binaries may or may not, depending on the particulars.
+
+echotest.sh
+-----------
+Generic script support for 'echo -n' feature for shells that do not
+support it natively.
+
+
+jvm/build.sh
+libjvm/build.sh
+main/build.sh
+test/build.sh
+jni/src/harmony/generic/0.0/build.sh
+jvm/clean.sh
+libjvm/clean.sh
+main/clean.sh
+test/clean.sh
+jni/src/harmony/generic/0.0/clean.sh
+jvm/common.sh
+libjvm/common.sh
+main/common.sh
+test/common.sh
+jni/src/harmony/generic/0.0/common.sh
+-------------------------------------
+Like at the top level, each relevant directory level has a build
+script that compiles the source code ('build.sh') and removes the
+output files from that build ('clean.sh').  These files share a
+common file ('common.sh') also.  The output of 'libjvm' is stored
+in a 'libjvm/lib' subdirectory, while the output of the other scripts
+is stored in a '______/bin' subdirectory.
+
+dox.sh
+undox.sh
+commondox.sh
+------------
+The logic behind the documentation build using Doxygen.  The output
+is stored by 'dox.sh' into a 'doc' subdirectory at this level, while
+the 'undox.sh' removes it.  They share a common file 'commondox.sh'.
+In order to speed up the documentation build during development,
+define the environment variable SUPPRESS_DOXYGEN_VERYCLEAN as any
+non-null string.  See logic of 'dox.sh' for other comments.
+
+dist-src.sh
+dist-doc.sh
+dist-bin.sh
+-----------
+Construct a source distribution and store it above the top of
+the directory tree in gzipped tar, where CONFIG_RELEASE_LEVEL is
+the release level defined the last time that 'config.sh' was run:
+
+    Type    Script       Output TAR file
+    ----    ------       ---------------
+    Source  dist-src.sh  ../../bootJVM-src-$CONFIG_RELEASE_LEVEL.tar.gz
+    (plus
+      docs)
+
+    Docs    dist-src.sh  ../../bootJVM-doc-$CONFIG_RELEASE_LEVEL.tar.gz
+
+    Binary  dist-src.sh  ../../bootJVM-bin-$CONFIG_RELEASE_LEVEL.tar.gz
+    (plus
+      docs)
+
+A side effect of the source distribution (only) is the creation of a
+file in this directory named 'bootJVM-docs.tar.gz'.  It is included
+in the distribution as a part of the deliverables and contains
+installable documentation files.  Its installation is managed with
+'config.sh' where it references the "pre-formatted documentation.
+
+Other Files
+===========
+
+INSTALL  <---  * * *   START HERE * * *
+-------
+Instructions for installing the source code and building the
+binaries and the documentation.
+
+LICENSE
+-------
+The Apache Software Foundation license text used by the ASF
+for all software distributions.
+
+README
+------
+This file.
+
+bootjvm.dox
+dox_filter.sh
+-------------
+'bootjvm.dox' is the Doxygen directive file used to create
+all project documentation,  invoked by 'dox.sh'.
+
+'dox_filter.sh' the  filter script declared in 'bootjvm.dox'
+for filtering input files.  It is declared as the
+'INPUT_FILTER=' parameter in 'bootjvm.dox' and is necessary
+to properly format all files that are not explicitly '.c'
+or '.h' or '.java' source files.
+
+svnstat.sh
+----------
+Sample script from Doxygen documentation to display the status of
+a file in SVN.  Not used in the project for any purpose.
+
+test/.project
+test/.classpath
+---------------
+Eclipse project files for the 'test' Java project.
+
+jvm/.project
+jvm/.cdtproject
+jvm/.cdtbuild
+libjvm/.project
+libjvm/.cdtproject
+libjvm/.cdtbuild
+main/.project
+main/.cdtproject
+main/.cdtbuild
+jni/.project
+jni/.cdtproject
+jni/.cdtbuild
+-------------------
+Eclipse project files for the several C/C++ projects.
+
+
+
+Output areas
+============
+
+bootclasspath/
+--------------
+Directory containing default value of BOOTCLASSPATH environment
+variable.  THIS ABSOLUTE PATH NAME IS COMPILED INTO SOURCE CODE
+AND WILL NEED TO ULTIMATELY BE PHASED OUT.
+
+config/
+-------
+Directory where all results from 'config.sh' are stored.  These
+files are used by the various shell scripts and by Doxygen to
+build various aspects of the project.
+
+jvm/bin
+main/bin
+test/bin
+jni/src/harmony/generic/0.0/bin
+-------------------------------
+Output area respectively from 'jvm/build.sh', 'main/build.sh',
+'test/build.sh', and 'jni/src/harmony/generic/0.0/build.sh'.
+
+libjvm/lib
+----------
+Output area from 'libjvm/build.sh'
+
+jni/bin
+-------
+Output area for the Eclipse 'jni' project.  Source distributions
+(via 'dist-src.sh') cannot be performed until this directory has been
+manually removed of an Eclipse 'clean' operation done for the
+'jni' project.
+
+
+Output files
+============
+
+bootclasspath/*.class
+bootclasspath/*/*.class
+--------------
+Java class files that are found in the BOOTCLASSPATH environment
+variable.  They are extracted from your JDK's runtime JAR file
+and are used to start up the JVM.  They will eventually get phased
+out of the project when these classes have been developed by the
+project team.  Whether or not replacements from the project are
+stored here is TBD.
+
+config/config.h
+---------------
+Although the other files stored in the 'config' directory are not
+listed here, they are derived along with this file from 'config.sh'
+to control the compile and run time features of the project.  This
+file specifically can be used as a reference when running 'config.sh'
+again to remember what settings were configured.  It will be very
+obvious from that script as to which definitions here match the
+questions.
+
+jvm/bin/bootjvm
+main/bin/bootjvm
+test/bin/*.class
+test/bin/*/*.class
+jni/src/harmony/generic/0.0/bin/bootjvm
+jni/src/harmony/generic/0.0/bin/*/*.class
+-----------------------------------------
+The output files respectively from the build of the 'jvm',
+'main', 'test', and 'jni/src/harmony/generic/0.0'
+project build.
+
+libjvm/lib/libjvm.a
+-------------------
+Output file from the 'libjvm' project build.
+
+
+Source code
+===========
+Following is a short description of each source file.  All function
+names start with the name of their source file, 'filename_function()'
+in keeping with the OO concept of packaging all related code and data
+into the same sourcefile.  See also 'jrtypes.h' for comments on naming
+conventions for certain data types.
+
+The JNI source code is grouped separately, as is the test suite.
+
+
+jvm/src/arch.h
+--------------
+Configure the compilation of each source file with architectural
+parameters, especially from the configuration script 'config.sh'.
+Provide copyright information for the binary edition of each source
+file.  This file MUST be included by all source files in
+'jvm/include' and in 'jvm/src'.  Do NOT include it in 'jni'
+source files.  There needs to be an equivalent for the Java code
+written for these features (see to-do item in source).
+
+jvm/src/argv.c
+--------------
+Parse the JVM command line.  For easy help, call program
+with '-help' option.
+
+jvm/src/attribute.c
+jvm/src/attribute.h
+-------------------
+Handle class file attributes.  The type definition
+'jvm_attribute_index' is the key to properly using class file
+attributes.
+
+jvm/src/bytegames.c
+-------------------
+Manipulate bytes for various purposes such as byte swapping, reading
+2-byte structures from 1-byte addresses, or 4-byte or 8-byte structures
+from 1- or 2-byte addresses, etc.  (These last are due to use of
+structure packing, especially in parsing class file data and parsing
+virtual opcode operands).
+
+jvm/src/cfattrib.c
+------------------
+Process the attibute fields of class file data.  Since attributes
+are a large and specialized area of the JVM spec class file
+definition, they have been broken out of 'classfile.c'.
+
+jvm/src/cfmacros.h
+------------------
+Macros for navigating the class file structures of 'classfile.h'.
+
+jvm/src/cfmsgs.c
+----------------
+Diagnostic messages for class file data.
+
+jvm/src/class.c
+jvm/src/class.h
+---------------
+Handle Java classes in the real machine implementation.
+The type definition 'jvm_class_index' is the key to properly
+using Java file classes.  Notice that this index is implemented
+in such a way that the underlying implementation could be
+completely changed from a simple array of structures to something
+unrelated and there would be only a few changes to some macros
+necessary to support that new implementation.  Such an implementation
+might call this type definition a 'jvm_class_hash' instead, for
+example.  The design decision, however, was to try to maintain a
+separate structure for classes than for objects.  Each class does
+have an object that contains its object-ish components.  This
+object is also implemented to satisfy the spec requirements that
+a class also have a class object.  See 'linkage.h' as to how to
+navigate between classes, objects, and threads.
+
+jvm/src/classfile.c
+jvm/src/classfile.h
+-------------------
+Definition of JVM spec, version 2, section 4, for JDK 1.5, namely,
+the class file structure, and its implemention.  The version of
+the class file definition (section 4) is listed near the top of
+the header file.  It is one of several that have been floating
+around, but appears to meet the JDK 1.5 attribute extensions
+rather exactly, and is _assumed_ (that is a VERY big assumption!)
+to be class file 'major.minor' version '49.0', namely the JDK 1.5
+class file format.
+
+
+All symbol definitions are declared _exactly_ as shown in this
+specification with the single exception of array declarations like,
+
+    u2      constant_pool_count;
+    cp_info constant_pool[constant_pool_count - 1];
+
+Such definitions are instead declared as,
+
+    u2      constant_pool_count;
+    cp_info **constant_pool;
+
+and an array of pointers to (cp_info) is allocated on the heap of
+size 'constant_pool_count'.  (In this one case, element zero is
+defined as not being used, so it is always a NULL pointer.)
+
+For purposes of real machine word alignment, type 'cp_info' and
+'attribute_info' have been embedded in a _slightly_ larger structure
+to keep 2- and 4-byte member references on the correct real machine
+address boundaries.  The embedding structures are called 'cp_info_dup'
+and 'attribute_info_dup', respectively, as they duplicate the contents
+of the smaller structure, if you will.
+
+All symbol definitions that are not _explicitly_ found in the spec
+are locally defined for use in this implementation.  They are prefixed
+with the string "LOCAL_" to distinguish them from spec definitions.
+For example, ACC_PUBLIC marks a class as public, but the local
+definition ACC_EMPTY means no defintion at all.  Since it is not
+found in the spec, it is actually named LOCAL_ACC_EMPTY here.
+
+
+jvm/src/classpath.c
+jvm/src/classpath.h
+-------------------
+Manage and navigate CLASSPATH environment variable.
+
+jvm/src/classutil.c
+-------------------
+Utilities for handing real machine class structures.
+
+jvm/src/exit.c
+jvm/src/exit.h
+--------------
+Exit codes for exit(3) and fatal error handing for JVM runtime.
+This code implements non-local subroutine returns using the
+standard library calls setjmp(3) and longjmp(3).  If you want
+to understand this non-local return mechanism, you _must_ read
+the man pages for these functions and study the examples.  They
+are extremely useful in processing fatal error conditions and
+state machine conditions under which there is no valid return
+or repair of an invalid state or irreconcilable condition.
+
+jvm/src/field.c
+jvm/src/field.h
+---------------
+Handle Java virtual machine variables for both class static fields
+and object instance fields.  The type definitions 'jvm_field_index'
+and 'jvm_field_lookup_index' are the keys to properly using Java fields.
+
+jvm/src/gc.h
+------------
+API for all garbage collection algorithms.
+
+jvm/src/gc_stub.c
+-----------------
+Default implementation of garbage collection (a do-nothing
+implementation).  This code is meant to be replaced by one
+or more GC algorithms.  The GC insertion points in the code
+body corporate should stand for all algorithms.  See 'heap_*.c'
+and header file 'heap.h' for an example of implementing
+multiple algorithms on a single API.
+
+jvm/src/heap.h
+--------------
+API for all heap management algorithms.
+
+jvm/src/heap_simple.c
+---------------------
+Default implementation of heap allocation using malloc(3)
+and free(3).  One option is presented to return an allocated
+area that has been initialized to zeroes, which is useful for
+structure initialization.
+
+jvm/src/heap_bimodal.c
+----------------------
+An improvement over 'heap_simple.c' where a large memory block
+is allocated from whence come all allocations up to a certain
+size.  Beyond that, the 'heap_simple.c' algorithm is used.
+
+jvm/src/jrtypes.c
+jvm/src/jrtypes.h
+-----------------
+Map Java data types ('j') to real machine ('r') types.  Much of the
+code uses these two letters prefixed to variable names to distinguish
+between Java and real machine data types.  The other common prefix
+used throughout the code is 'p' for pointer, such as '(char *) pstr'
+or '(jint *) parray'.  However, this convention is for instances of
+pointers to _any_ data type, and may be used for either the 'C' or
+the Java domains.  Compiled constant definitions are found
+in 'jrtypes.c' also.
+
+jvm/src/jvalue.h
+----------------
+Java data type aggregate for storage of class static field
+and object instance fields.  One type fits all.
+
+jvm/src/jvm.c
+jvm/src/jvm.h
+-------------
+The main JVM control structure for running the Java virtual
+machine on this real machine.  There is virtually no global
+storage in this code, and only sparing use of static (file scope)
+storage.  Most everything else is either found here, is a
+local variable, or is on the heap.  The code in 'jvm.c' initializes,
+runs, and shuts down the JVM.
+
+jvm/src/jvmcfg.c
+jvm/src/jvmcfg.h
+----------------
+Top-level configuration of JVM parameters (not including what is
+mostly compile-time setup with 'config.sh' and its 'config/config.h'
+header file.)  All sorts of things are defined here, from OS-dependent
+directory delimiters to JVM command line parameter strings.  A number
+of significant typedefs are also found here, as well as high and
+low limits on data types, etc.  Compiled constant definitions are
+found in 'jvmcfg.c' also for NULL and BAD definitions for major
+typedefs.
+
+jvm/src/jvmclass.h
+------------------
+Fully qualified class name strings (internal form) for a wide
+variety of classes needed by the JVM at run time.  Of special
+significance is a large number of error and exception classes.
+
+jvm/src/jvmregs.h
+-----------------
+Definition of JVM program counter, stack, and stack navigation.
+
+jvm/src/jvmutil.c
+-----------------
+Utilities for debug message levels, stack dumps, etc.
+
+jvm/src/linkage.c
+jvm/src/linkage.h
+-----------------
+The header contains linkages between class, object, and thread
+structures.  The source file
+contains late binding linkage functions to link field references
+and method references from one class into their definitions in
+another class.
+
+jvm/src/main.c
+main/src/main.c (symbolic link to jvm/src/main.c)
+---------------
+A sample main() entry point that calls the JVM from either a
+library archive or by direct object linkage.
+
+jvm/src/manifest.c
+------------------
+Read and process selected properties from a JAR manifest file.
+
+jvm/src/method.c
+jvm/src/method.h
+----------------
+Handle Java virtural machine methods.  The type definition
+'jvm_method_index' is the key to properly using Java methods.
+
+jvm/src/native.c
+jvm/src/native.h
+----------------
+Support for JNI native methods and what are called local native
+methods (those with intimate knowledge of the inner workings of
+the JVM).  Local native methods may, but are not required to, use
+the JNI interface, but a significant shortcut is provided for more
+direct connection between them and the JVM.
+
+jvm/src/nts.c
+jvm/src/nts.h
+jvm/src/unicode.c
+jvm/src/unicode.h
+jvm/src/utf8.c
+jvm/src/utf8.h
+-----------------
+Utilities for null-terminated strings, UTF8 strings, and Unicode
+strings, including conversion back and forth, getting and putting,
+length functions, and examination/conversion of Java class formatting
+in various types.  Notice that there are three types of strings
+in this JVM:  (1) 'C' style strings of ASCII characters terminated by
+an ASCII '\0' (NUL) byte, also known as "pointer to real-machine
+character" strings, or 'prchar' variables; (2) UTF8 strings as
+implemented with the (CONSTANT_Utf8_info) type definition, particularly
+as related to Java class files; (3) Unicode strings, which consist of a
+(jchar)[] type array variable and a (u2) length variable.
+
+jvm/src/object.c
+jvm/src/object.h
+----------------
+Handle Java objects in the real machine implementation.
+The type definition 'jvm_object_hash' is the key to properly
+using Java objects.  Notice that this hash is implemented
+in such a way that the underlying implementation could be
+completely changed from a simple array of structures to something
+unrelated and there would be only a few changes to some macros
+necessary to support that new implementation.  See 'linkage.h'
+for how to navigate between classes, objects, and threads.
+
+jvm/src/objectutil.c
+--------------------
+Utilities for Java objects.  Support for synchronize()
+and unsynchronize() is found here, namely, the object monitor
+locks.  Other utility functions may be placed here as appropriate.
+
+jvm/src/opcode.c
+jvm/src/opcode.h
+----------------
+The JVM spec, version 2, section 9, operation code list is found
+in the header file directly as defined in the spec.  The code
+contains the JVM inner execution loop.
+
+jvm/src/stdio.c
+---------------
+Standard input/output functions for stdout, stderr, buffer formatting,
+etc.  CAVEAT EMPTOR (let the buyer beware!):  This file does _NOT_ use
+structure packing because on the original implementation (Solaris 9
+with GCC 3.3.2), the standard I/O library was _not_ compiled with
+structure packing and caused strange runtime errors and SIGSEGV on
+normal library calls.  Therefore, most standard I/O was gathered into
+this file, with the exception of 'manifest.c', which does not seem
+to have to problem.
+
+jvm/src/thread.c
+jvm/src/thread.h
+----------------
+Handle JVM threads in the real machine implementation.
+The type definition 'jvm_thread_index' is the key to
+properly using threads.  Notice that this index is
+implemented in such a way that the underlying
+implementation could be completely changed from a
+simple array of structures to something unrelated
+and there would be only a few changes to some macros
+necessary to support that new implementation.  See 'linkage.h'
+for how to navigate between classes, objects, and threads.
+
+jvm/src/threadstate.c
+---------------------
+Thread state machine individual states.
+A lengthy narrative near the beginning of this file defines
+the JVM thread state machine, which is then implemented in 'jvm.c'
+by jvm_run().
+
+jvm/src/threadutil.c
+--------------------
+Utilities for normal operation of the thread state machine.
+
+jvm/src/timeslice.c
+-------------------
+Real-time JVM time slice timer for limiting the amount of time
+that a thread may run (see also 'jvm.c' and 'opcode.c') before
+the next thread is given some time.
+
+jvm/src/tmparea.c
+-----------------
+Private disk storage area for running the JVM.  It is set up and
+torn down by this code and is referenced through a getter function.
+
+jvm/src/util.h
+--------------
+Miscellaneous support macros and function prototypes from various
+of the source files.  This file contains a list of which source
+files have their prototypes listed here, and those that could
+but do _not_ for specific reasons.
+
+
+A WORD ABOUT FUNCTION PROTOTYPES
+================================
+Each and every source 'filename.c' that has a 'filename.h' associated
+with it will locate its function prototypes in that header file.
+The few exceptions are listed in 'jvm/src/util.h'.
+
+
+A WORD ABOUT SOURCE FORMATTING
+==============================
+Each and every source file is formatted so that not one single line
+goes beyond 72 characters in width except where absolutely unavoidable.
+Furthermore, there is not one single TAB character (ASCII 9, 011,
+0x09, \u0009) in the entire body of code.  The only place it is found
+is in theEclipse '.project' and '.classpath' files.  All indentions
+are made at 4-column intervals.
+ 
+The purpose of these two constraints is so that absolutely anyone with
+any text editor may view the source in a standard 80-column text editor,
+with line numbers, and be able to see the whole line without any line
+wrapping.  This constraint makes the interchange of source code
+between project contributors much simpler.  Although there is a case
+to be made for wider lines, many developers like 80 column constraints
+anyway, or some other number.  This choice of constraint should provide
+maximum flexibility of interchange of source files amongst all
+contributors.
+
+
+JNI SOURCE CODE
+===============
+
+jni/src/harmony/generic/0.0/src/java/lang/Object.java
+jni/src/harmony/generic/0.0/src/java/lang/Class.java
+jni/src/harmony/generic/0.0/src/java/lang/String.java
+jni/src/harmony/generic/0.0/src/java/lang/Thread.java
+-----------------------------------------------------
+Sample segments of java.lang.* package that contain the
+native declarations in these classes.  (Not comprehensive
+either for each class or for the package.)
+
+jni/src/harmony/generic/0.0/include/java_lang_Object.h
+jni/src/harmony/generic/0.0/include/java_lang_Class.h
+jni/src/harmony/generic/0.0/include/java_lang_String.h
+jni/src/harmony/generic/0.0/include/java_lang_Thread.h
+------------------------------------------------------
+JNI headers that correspond to the 'src/java/lang' equivalent
+Java source files in the java.lang.* package that contain the
+native declarations in these classes.  (Not comprehensive
+either for each class or for the package.)
+
+jni/src/harmony/generic/0.0/src/java_lang_Object.c
+jni/src/harmony/generic/0.0/src/java_lang_Class.c
+jni/src/harmony/generic/0.0/src/java_lang_String.c
+jni/src/harmony/generic/0.0/src/java_lang_Thread.c
+--------------------------------------------------
+JNI source code that correspond to the 'src/java/lang' equivalent
+Java source files in the java.lang.* package that contain the
+implementation of the local native methods in these classes.
+(Not comprehensive either for each class or for the package.)
+
+jvm/include/jlObject.h
+jvm/include/jlClass.h
+jvm/include/jlString.h
+jvm/include/jlThread.h
+----------------------
+Headers for connecting the JVM to the JNI interface of the above
+classes.  There are effectively two parallel sets of runtime
+definitions in these files, one for generic JNI, one for the
+core JVM code, namely this body of source.  They are
+_independent_ so there is NO coupling between an arbitrary
+JDK's JNI implementation and this JVM.  Please see comments
+in these header files for more information.
+
+jvm/src/jlObject.c
+jvm/src/jlClass.c
+jvm/src/jlString.c
+jvm/src/jlThread.c
+------------------
+The native side of the JNI implementation of the above selected
+core java.lang.* classes.  The functions in these files are
+referenced by the JNI target functions.  For example, the
+function java_lang_Class_isPrimative() in 'java_lang_Class.c'
+will at some point call the 'jlClass_isPrimative()' function
+in 'jlClass.c'.
+
+jni/src/harmony/generic/0.0/src/sampleJNImain.c
+-----------------------------------------------
+Sample function that calls JNI functions through the JNI interface.
+This is currently built as a straight binary.  It needs to be built
+as a .so/.dll shared object file.
+
+
+TEST JAVA FILES
+===============
+This area is designed to be filled in with _many_ packages and
+classes for testing the JVM.  Here is a rudimentary but useful
+first pass:
+
+
+test/src/HelloWorld.java
+------------------------
+Just what it says.  In order to run this main() method, however,
+requires a _fully_ functional JVM with most of the basic JNI in
+place.
+
+test/src/harmony/jvm/test/PkgHelloWorld.java
+--------------------------------------------
+The same "hello world" program, but in a package.
+
+test/src/harmony/jvm/test/MainArgs.java
+---------------------------------------
+A main() method that takes arguments from the command line.
+
+
+
+KNOWN ISSUES AND SUGGESTED TO-DO ITEMS
+======================================
+
+(1) The default garbage collection algorithm is 'no collection'.
+This means that an algorithm must be written in order to sustain
+JVM execution with continuous heap availability.  Other heap
+implementations might also be written beyond the two that are
+supplied.
+
+(2) Anonymous strings (without a class static field reference in
+(rclass) or an object instance reference in (robject) may not get
+completely unreferenced and deallocated, but could continue to
+accumulate instance references.  Depending on the GC algorithm, this
+may or may not occur and/or may or may not present a problem over a
+very long JVM session where reference structures grow without bound
+or counts wrap around to zero.
+
+(3) There has been no attempt made to process any special values
+of floating point data, neither NAN, +/- infinity, overflow, or
+anything else.  The definitions per the class file spec are present,
+of course, but nothing has been done with them.  Special care should
+be taken in fprintf() statements-- like the sysDbgMsg() calls in
+'cfmsgs.c' -- to make sure that formats like "%lf" are followed and
+precise.  The same goes for 64-bit integers, (long long) in real
+machine and (jlong) in JVM, that formats like "%ld" are followed
+and precise.
+
+(4) All reading of JAR files uses the 'jar' utility provided in
+the $JAVA_HOME directory tree in '$JAVA_HOME/bin/jar'.  This will,
+of course, need to be enhanced to simply read the JAR files directly.
+To start with, the BOOTCLASSPATH could have them added to it as a
+part of 'config.sh', then invoked from the JVM.
+
+(5) The JNI interface in 'jni/src/harmony' contains only a cursory
+JNI implementation.  This will need to be filled out to the complete
+suite of native methods needed by java.lang.*.  The native side is
+found in 'jvm/include' for the 'jni/src/harmony' source
+and header files, while the implementation is in the
+'jvm/src/jlClassNameXYZ.c' files (all beginning with 'jl' for
+"java/lang" followed by the actual class name).  For example,
+'jlThread.c' contains the native portions of java.lang.Thread.
+Certain key system calls like open(2) and exit(2) and socket(2)
+are located in packages like 'java.io' and 'java.system' and
+'java.rmi' (?), respectively.  The local native method interface
+will need to be extended to cover these system calls.
+See also item (28) below.
+
+(6) The JVM execution engine in particular will need through testing.
+It has been unit tested, of course, but good, solid integration
+testing is an excellent exercise for new contributors to learn the
+code, so this item has been specifically reserved for contributors
+for this purpose.
+
+(7) There is apparently a typographical error in the spec section
+4.5.7 describing 21-bit character encoding.  Therefore, this format
+has not been implemented pending proper resolution.  It probably is
+correct to assume that the spurious "-1" in the second byte of the
+first triple should say "(bits 20-16)" instead of "(bits 20-16)-1".
+However, this is presented as an exercise for contributors.
+
+(8) There are a plethora of comments marked "@todo xxx" all over the
+code.  In the Doxygen "Related Pages" section, they are gathered into
+one comprehensive list.  These items are presented as exercises for
+contributors.
+
+(9) The Solaris 32-bit implementation was chosen for development as a
+very generic development and runtime environment.  Testing partway
+through indicated that a transition to a 64-bit runtime environment
+could be compiled with little effort.  However, there will have to
+be some adjustments to get everything to work because that one test
+produced a SIGSEGV during JVM initialization, and its cause was not
+thoroughly explored.  Every effort has been made to anticipate 64-bit
+compilations, but that adjustment will need to be fully tested.
+
+(10) Every effort has been made to use _only_ standard Unix and
+Posix runtime library calls so the code could be ported to as many
+platforms as possible.  The first targets that come to mind are,
+of course, Linux, HP-UX, and AIX, with CygWin in mind also, with
+a few changes for system(3) scripts.  (*** The code intentionally
+does _NOT_ have the Windows version of some CONFIG_xxxx_SCRIPT
+definitions so that the contributor will need to get it written,
+possibly put into a .BAT file, then invoked through the existing
+infrastructure in the code. ***)
+
+(11a) There are a number of places here and there in the code where a
+return value is not properly checked for having an error value, such
+as 'jvm_class_index_null' or 'jvm_attribute_index_bad'.  This
+is typically _not_ a throwable error condition, like from heap
+allocation or other error, but is an actual runtime condition
+that is returned.  After three full passes through the code,
+the error code structure has morphed significantly from a fully
+structured approach just to get the code started to a partial OO
+approach, throwing errors through setjmp(3)/longjmp(3).  Someone
+needs to go through the code in its _entirety_ and find out where
+invalid results are intentionally returned instead of throwing an
+error and _make sure_ that the calling functions check those results
+properly.
+
+(11b) The same goes for input parameters in various places
+throughout the code for the following typedefs from 'jvmcfg.h':
+    jvm_thread_index
+    jvm_constant_pool_index
+    jvm_interface_index
+    jvm_class_index
+    jvm_method_index
+    jvm_field_index
+    jvm_field_lookup_index
+    jvm_attribute_index
+    jvm_unicode_string_index
+    jvm_object_hash
+
+These will need to be reviewed for the same reasons as the error
+return codes.  Either they will index an array to its NULL element,
+specifically (with corresponding NULL element named also),
+
+    jvm_thread_index (jvm_thread_index_null)
+    jvm_constant_pool_index (jvm_constant_pool_index_null)
+    jvm_class_index (jvm_class_index_null)
+    jvm_object_hash (jvm_object_hash_null)
+    jvm_native_method_ordinal (jvm_native_method_ordinal_null)
+
+which, in the case of a 'jvm_constant_pool_index' will produce
+a NULL pointer SIGSEGV, or it will index way off the end at the
+max index for the data type, namely (with corresponding BAD
+element name also),
+
+    jvm_interface_index (jvm_interface_index_bad)
+    jvm_method_index (jvm_method_index_bad)
+    jvm_field_index (jvm_field_index_bad)
+    jvm_field_lookup_index (jvm_field_lookup_index_bad)
+    jvm_attribute_index (jvm_attribute_index_bad)
+    jvm_unicode_string_index (jvm_unicode_string_index_bad)
+
+A typical check might be,
+
+    jvm_attribute_index
+       attribute_find_in_field_by_cp_entry(jvm_class_index clsidx,...)
+    {
+        if (jvm_class_index_null == clsidx)
+        {
+            /* Somebody goofed * /
+            exit_init_failure(EXIT_JVM_INTERNAL,
+                              JVMCLASS_JAVA_LANG_INTERNALERROR);
+    /*NOTREACHED* /
+        }
+    }
+
+In all cases, a review of the code with format input parameters
+to test what goes in is simple-- there are quite a few places
+where this _is_ done, it just is not complete.  A similar
+review of functions that pass these data types back _out_ will
+provide the inverse test.  Both are _mandatory_ for integrity
+of the runtime environment.
+
+(12) The threading algorithm uses a simple for() loop.  It could
+be easily generalized to using POSIX threads since there is already
+one POSIX thread started in the current code.  This thread would go
+away when and if such threading were implemented.  This thread is
+implemented in 'timeslice.c'.  It is a time slice real-time clock
+timer that sends SIGALRM every so often on a tick boundary.  This
+signal is connected to a handler that sets a flag in each live
+JVM thread and tells the JVM inner loop to quit after the current
+operation code so the next thread can be activated.  By unwinding
+the thread activation for() loop, also known as the JVM outer loop,
+and putting in place a POSIX thread for each JVM thread, the timer
+would go away and the code would become a true multi-threaded
+application.  
+
+The purpose of _this_ implementation as a for() loop is for simplicity
+of implementation and for education of contributors who are new to
+multi-threaded environments in general and the Java virtual machine
+multi-threaded environment in particular.  (Note that such unwinding
+would take place exclusively in 'thread.c'.  No other logic
+_anywhere_ should be affected in more than a minor way beyond the
+JVM outer look in 'jvm.c'.)
+
+(13) Commensurate with the above discussion on unwinding the JVM
+outer loop into a multi-threaded application is the discussion of
+write barriers.  THERE ARE ABSOLUTELY NO WRITE BARRIERS IN THIS
+DESIGN!!!  This is both for simplicity (per above reasons) and so
+that this _critical_ subject is given due consideration by the
+whole team JVM architecture contributors.  This implementation
+makes no claims toward being an authority on such a vital and
+potentially sensitive subject.
+
+(14) The 'field_info' area of the class file definition supports
+the 'ConstantValue' attribute, but does not support 'Signature'.
+This needs to be added for conformance to JDK 5 requirements.
+It also should support 'Synthetic' and 'Deprecated'.  The definitions
+are present in 'classfile.h', they just need to get implemented.
+
+(15) The 'method_info' area of the class file definition supports
+the 'Code' and 'Exceptions' attributes, but does not support
+'Signature'.  This needs to be added for conformance to JDK 5
+requirements.  The definitions are present in 'classfile.h', they
+just need to get implemented.
+
+(16) When nearing the end of the initial development, I ran across
+what is probably a memory configuration limit on my Solaris platform,
+which I did not bother to track down, but rather worked around.  It
+seems that when calling malloc(3C) or malloc(3MALLOC), after 2,280
+malloc() allocations and 612 free() invocations, there is something
+under the covers that does a SIGSEGV, and it can happen in either
+routine.  I therefore extended the heap mechanism of 'heap_simple.c'
+to allocate a large number of slots of 'n' bytes for small allocations
+up to this size.  Everything else still uses malloc().  In this way,
+I was able to finish development on the JVM without arguing with heap
+allocation.  This implementation is found in 'heap_bimodal.c'.  (In
+other words, I will let the team fix it!)  Furthermore, I am not sure
+that the real project wants a static 'n + 1' MB data area just hanging
+around the runtime just because I did not take time to tune the system
+configuration!
+
+(17) In preparation for writing the actual JVM execution engine,
+the 'bytegames.c' utilities bytegames_getrl8() and bytegames_putrl8()
+and bytegames_swap8() and bytegames_mix8() were added.  The 'util.h'
+macros GETRL8() and PUTRL8() were likewise added.  Other ways of
+processing 64-bit values were obsoleted and the places where they were
+used have been replaced by these functions and macros.  This
+substitution needs to be more rigorously tested.  All places where
+this substitution was made have been marked as commented-out code
+plus new functionality with a @todo item commenting it.
+
+(18) There needs to be an examination of heap usage to make _sure_
+that all instances of HEAP_GET_xxxx() eventually have a matching
+HEAP_FREE_xxxx() so there are no memory leaks.  The existing code
+has been carefully written to facilitate this requirement, but
+it has not been rigorously regression tested.  And since it is _well_
+known that memory leaks are a system integrator's worst nightmare,
+if the code is checked early on into the project, there will be
+nothing to lose sleep over later on.
+
+(19) A review of the non-local return logic in 'opcode.c' from threads
+that throw a java.lang.Error, java.lang.Exception, and
+java.lang.Throwable is in order.  Errors should kill the JVM, but
+Exceptions should allow it to proceed.  What about Throwables?
+The framework is in place for the project team to adjust to meet
+the JVM spec.  Also, make sure that simply creating a new class
+object, running its <init> method, and continuing with previous code
+or quitting is the right way to process the condition.  The existing
+logic is from heuristic observation of a JVM, but an examination of
+the spec should provide the definitive answer.  Notice that
+java.lang.Throwable and java.lang.StackTraceElement will need local,
+native implementations.  The exception framework needs to be filled in
+in opcode_run() for exceptions thrown by Java virtual methods.  All
+handling of errors like java.lang.NoSuchMethodError is already taken
+care of.
+
+(20) The concept of the ThreadGroup is not implemented here (see JVM
+spec section 2.16).  This is given as an exercise to the project team.
+The default implementation consists _ONLY_ of the method
+java.lang.ThreadGroup.uncaughtException().  The rest of this class
+must be implemented.  This partial implementation may also need to
+go away at that time.  The basic reasoning for this is that the
+functionality of java.lang.ThreadGroup does not seem to warrant
+any native methods.  Therefore, the whole of its functionality should
+likely be implemented in a Java class library and should typically
+behave properly without direct JVM core support.
+
+(21) The sequence of loading and initializing the three critical
+classes java.lang.Object, Class, and String in 'jvm_init()' is
+somewhat fragile and probably not really sustainable.  It might be
+that the best thing to do is to either make classlib-specific
+implementations of this initialization or to unload and reload these
+classes once the original loading is done and let the normal <clinit>
+be performed during this second attempt to load each of these classes.
+The problem is one of chickens and eggs:  Which comes first?  The
+logic is written and somewhat tested.  It needs to be firmed up.
+An exercise for the team.  Unloading and reloading support is already
+provided with class_static_delete() and class_reload().
+
+(22) The verification step (VM spec section 2.17.3) is given as an
+exercise for the project team.  This was done in the interest of time
+and the fact that there may be third-party packages that may do this
+nicely (BCEL?) without much further effort.
+
+(23) The source code is documented using Doxygen in its normative
+state.  Although this tool can be _significantly_ contorted to perform
+documentation of almost _any_ file type due to its capability to hook
+into a user-specfied input filter, this implementation has done
+nothing outside of the usual bounds of the default product
+configuration.  With that said, there is _one_ small admission to make
+here:  Even though all of the code was written in ANSI 'C', the OO
+concept of throwing exceptions is intrinsically bound up with the
+runtime needs of a Java Virtual Machine.  Therefore, one _small_
+bending of the rules was permitted in the documentation-- use of the
+C++ documentation keyword '@throws' (also known as '@exception' and
+'@throw').  Functions that instantiate a java.lang.Throwable such as
+'Error' or 'Exception' (and/or their subclasses) use the following
+documentation syntax to present this behavioral feature to the
+Doxygen output.  The results will show up in the bolded section named
+'Exceptions:' in the same way that parameters show up in the
+'Parameters:' section and return values in the 'Returns:' section:
+
+ *
+ * @brief Function fn() doc header
+ * ...
+ * other doc info...
+ * ...
+ *
+ * @param p1 what parm 1 does
+ *
+ * @returns what fn returns
+ *
+ * @throws JVMCLASS_some_kind_of_exception_string_name
+ *         @link \#JVMCLASS_some_kind_of_exception_string_name
+ *         brief description of how to make this happen @endlink.
+ * /
+
+#include "exit.h"
+#include "jvmclass.h"
+
+rettype fn(parmtype p1)
+{
+    ...
+    if (problem_happened)
+    {
+      exit_throw_exception(JVMCLASS_some_kind_of_exception_string_name);
+/*NOTREACHED* /
+    }
+
+    ...
+
+    return(normal_value);
+}
+
+Notice this function call is similar to exit_jvm(), but has the
+added feature of initiating an exception, after which exit_jvm()
+will be called with an appropriate exit code to shut down the JVM.
+
+
+(25) When using the Eclipse C/C++ plugin, be aware of a bug in
+that code:  Sometimes it loses its brains and wants to debug the
+test Java program instead of the C program.  Look at the Run menu's
+Debug dialog (Run|Debug) and you will notice that under "C/C++ Local
+Application", the 'jvm' configuration is missing.  To correct
+this, simply click on "C/C++ Local Application" and then click "New":
+
+Main:
+    Project:                         jvm
+    C/C++ Application:               bin/bootjvm
+    Connect process input & output
+      to a terminal:                 yes
+Arguments:
+    C/C++ Program Arguments:         (anything appropriate)
+    Use default working directory:   yes
+Environment:
+    (anything you like)
+Debugger:
+    Debugger:                        GDB Debugger
+    Stop in main() on startup:       yes (typically, no is okay)
+    Main:
+        GDB debugger:                gdb
+        GDB command file:            <empty>
+    Share Libraries:
+        (anything you like)
+Source:
+    jvm                              yes
+    test                             yes
+Common:
+    Type of launch configuration:    local
+    Display in favorites menu:       (anything appropriate)
+    Launch in background:            yes
+
+Now click 'Apply' and 'Close'.  This should save it properly.
+Now it may be used normally.
+
+
+(24) A solid introductory project for someone is to go in to
+'cfmsgs.c' and write and equivalent to cfmsgs_show_constant_pool()
+for the field table and method table, suggested names being,
+cfmsgs_show_fields_table() and cfmsgs_show_methods_table().
+This method takes cfmsgs_typemsg() and displays each constant_pool[]
+item.  The same approach could be taken to these two utilities.
+The first and most important use of these functions is in
+classfile_loadclassdata().
+
+In like manner, an attribute table display function needs to
+be written to do the same thing for any attributes table.
+Currently  cfmsgs_atrmsg() shows the contents of a _single_
+attribute, but there is nothing that can explicitly dump
+an entire attribute table for fields, methods, or the (single)
+class attribute table.
+
+(25) While working on the above 'cfmsgs.c' display routines,
+that same person should probably go in to classfile_loadclassdata()
+and clean up the numerous individual cfmsgs_typemsg() calls for
+inclusion in those routines.  A few should probably still be
+left in, such as 'cfmsgs_typemsg("this", pcfs, pcfs->this_class)'
+which reports the 'this_class' member, but this process was followed
+when writing cfmsgs_show_constant_pool() and it helped the readability
+of the output _immensely_ to get rid of 'ad hoc' debug messages.
+
+(26) The debug message level (DML) values need to be completely
+overhauled for more effective use by developers.
+
+(27) Does there need to be a tighter relationship between the
+declaration of a native method via ACC_NATIVE when the class file
+is loaded by classfile_loadclassdata() and the class resolution
+logic of the linkage_resolve/unresolve_class() methods?  What
+about with thread_class_load() and related startup code that runs a
+method?
+
+(28) Although there have been _several_ significant passes at
+desk-debugging 'threadstate.c' and 'threadutil.c' and in particular,
+'jlThread.c', the JVM thread state machine needs a rigorous pass at
+integration testing.  The java.lang.Thread methods of 'jlThread.c'
+and 'threadstate.c' are of particular concern, along with the hooks
+in 'timeslice.c'.  This testing has been left as an exercise
+for the project team.  Someone who has completed their Sun
+Certified Java Developer certification and is good with skills
+in 'C' should be able to firm up this area of the code nicely.  See
+also item (5) above.
+
+(29) In like manner to (28) above, unit testing of object monitor
+locking has been left as an exercise for the project team.  Again,
+someone who has completed their Sun Certified Java Developer
+certification and is good with 'C' should be able to firm up
+this area of the code nicely.
+
+(30) The whole body of code needs to be reviewed for proper ordering
+of PUSH() and POP() macros for (jlong) and (jdouble) variables.
+The same goes for local variable access of the same.  The way it
+_should_ be done at this time is PUSH(MS), PUSH(LS) with corresponding
+POP(LS), POP(MS).  For local variables, var[n] := MS, var[n+1] := [LS].
+However, this needs proper scrutiny for completeness and correctness.
+
+(31) A review needs to be made of the Eclipse project files.  In
+particular, do the C/C++ project settings need to be made independent
+of the workspace settings for compile, link, and library archiver
+options?  Do the Java project settings need to be made similarly
+independent?  Should there be a workspace provided in the distribution
+that has all these things set up?  Currently, the projects are a bit
+of a mixture of workspace and project settings.  The 'build.sh'
+scripts use a hard-coded set of GCC options that are derived from the
+Eclipse setup.  The 'config/*.gcc' and config/*.gccld' files reflect
+this for the C source.  The Java compilations in the 'build.sh'
+scripts use the default Java compiler options.  Does there need to be
+a harmonization (sic) between the Eclipse and 'build.sh' settings?
+Should they be manually mantained in Eclipse and 'config.sh'?  These
+are questions that need some review.  Furthermore, this author is very
+much a proponent of systematic use of 'gmake' as a premier project
+build tool across the industry.  It would be a really good idea for
+use of 'gmake' to be reviewed.  It is used internally by Eclipse,
+but users should not be forced to use Eclipse just to get 'gmake'.
+
+(32) The inner loop of virtual instructions in opcode.c checks various
+items at run time such as ACC_STATIC and ACC_FINAL and other items
+that a class verifier should test.  This is done so that the code
+corresponds _directly_ with the definition of each instruction as
+described in JVM spec section 6.  Many of these these tests (namely,
+the examples above) should be moved to a byte code verifier because
+they will not change from the time that the class is loaded until it
+is unloaded. Obviously, checking them each time a virtual instruction
+is run is _not_ efficient at run time!  However, this implementation
+is meant also to teach the principles and requirements of virtual
+instructions, so the implementation of the JVM spec requirement was
+done in the inner loop in opcode_run() as a sort of reference
+implementation of each virtual instruction.
+
+(33) One very good exercise for project team members to learn this
+code will be to implement the exception logic as found in the
+exception attribute of the program counter, namely jvm_pc.excpatridx.
+This field is filled in correctly at method startup time, and there
+should be enough hooks in the structure of the code to implement it
+without much effort.  What will be worth it is the learning process.
+This logic will bear some strong similarities with LATE_CLASS_LOAD()
+and class_load_resolve_clinit() when not using the system thread.
+
+(34) It is similarly left as an exercise for the project team to
+locate a method in a superclass or an interface if it is not found
+in the current class.  Currently, a request is made for a method
+in the current class and a (jvm_method_index) is returned.  This is
+fine for JVM initialization when it is known which methods are
+found where, but what _should_ happen in normal JVM runtime is that
+the INVOKEVIRTUAL, INVOKEINTERFACE, INVOKESTATIC, etc., should check
+if a method is in the current class.  If not, check superclasses
+until no more superclasses.  If found, return a heap pointer that
+contains the (jvm_class_index) and (jvm_method_index) of the located
+method, otherwise return 'rnull', the NULL pointer.  Class loading
+does search for superclasses, so look for uses of 'pcfs->super_class'
+or 'pcfs_recurse->super_class' for examples on how to do this.
+
+(35) In the documentation, the @def and @struct tags were used
+to introduce specific definition types.  This practice somehow
+was not carried through to all definitions.  Similar cleanup should
+be done for the following tags:  @enum, @fn, @var, @typedef.  None
+of these were put in place, but would clean up the organization of
+the output areas and add better indexing capabilities to the result
+set.  It also might ease the need for @link tags so that definitions
+may be automatically tagged better, making room for cleanup of such
+constructions in the narrative as:
+
+    @link \#jvm_class_index jvm_class_index@endlink
+
+to be simplified into,
+
+    jvm_class_index
+
+This would then ease the readability (in source code itself) of the
+documentation.  Notice that constructions such as,
+
+    @link \#jvm_class_index a resulting class index@endlink
+
+will not need cleanup since the target link is not the same as the
+displayed text.
+
+(36) An excellent tutorial for learning how objects are created using
+non-default constructors is in jvm.c and class.c where string
+parameters are loaded in from the argv[] command line and from
+CONSTANT_String_info structures of the class file, respectively.
+A suggestion is made in jvm.c as to how to accomplish this.
+
+(37) After going back and forth as to whether or not a @throws
+condition that happens in a subroutine should also be reported
+back up the line in the function that called it, the result is
+that sometimes it is reported and sometimes it is not.  This needs
+to be regularized.  It is recommended to _not_ report it in the
+calling function's documentation also since this is really not
+an OO environment.  Document it where it happens and let that stand.
+
+@endverbatim
+#
+#/
+#/ /* 
+# (Use  #! and #/ with dox_filter.sh to fool Doxygen into
+# parsing this non-source text file for the documentation set.
+# Use the above open comment to force termination of parsing
+# since it is not a Doxygen-style 'C' comment.)
+#
+# EOF

Added: incubator/harmony/enhanced/trunk/sandbox/contribs/bootjvm/bootJVM/bootJVM-docs.tar.gz
URL: http://svn.apache.org/viewcvs/incubator/harmony/enhanced/trunk/sandbox/contribs/bootjvm/bootJVM/bootJVM-docs.tar.gz?rev=307257&view=auto
==============================================================================
Binary file - no diff available.

Propchange: incubator/harmony/enhanced/trunk/sandbox/contribs/bootjvm/bootJVM/bootJVM-docs.tar.gz
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: incubator/harmony/enhanced/trunk/sandbox/contribs/bootjvm/bootJVM/bootjvm.dox
URL: http://svn.apache.org/viewcvs/incubator/harmony/enhanced/trunk/sandbox/contribs/bootjvm/bootJVM/bootjvm.dox?rev=307257&view=auto
==============================================================================
--- incubator/harmony/enhanced/trunk/sandbox/contribs/bootjvm/bootJVM/bootjvm.dox (added)
+++ incubator/harmony/enhanced/trunk/sandbox/contribs/bootjvm/bootJVM/bootjvm.dox Fri Oct  7 21:27:56 2005
@@ -0,0 +1,335 @@
+########################################################################
+#
+# bootjvm.dox
+#
+# Doxygen setup and controls for Apache Harmony 'bootJVM' project.
+#
+# Doxygen control file for extracting and formatting documentation 
+# from source code.  No Doxygen control tags are used herein.  ;-)
+#
+#
+# $URL: https://svn.apache.org/path/name/bootjvm.dox $ $Id: bootjvm.dox 0 09/28/2005 dlydick $
+#
+# Copyright 2005 The Apache Software Foundation
+# or its licensors, as applicable.
+#
+# Licensed under the Apache License, Version 2.0 ("the License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+# either express or implied.
+#
+# See the License for the specific language governing permissions
+# and limitations under the License.
+#
+# $LastChangedRevision: 0 $
+#
+# $LastChangedDate: 09/28/2005 $
+#
+# $LastChangedBy: dlydick $
+# Original code contributed by Daniel Lydick on 09/28/2005.
+#
+########################################################################
+#
+# --- PROJECT RELATED OPTIONS ---
+#
+# Top level parameters-- See program equivalents in 'arch.h'
+#
+#
+# When modifying the program name, SET THE SAME WAY IN 'arch.h' !!!
+#
+# They are found there as 'ARCH_PROGRAM_NAME/ARCH_PROGRAM_DESCRIPTION'
+# and 'ARCH_PROGRAM_VERSION', respectively.
+#
+
+# defined in 'config/config_dox_setup.dox'.
+# Also paired up in 'config/config.h':
+#    "CONFIG_PROGRAM_NAME: CONFIG_PROGRAM_DESCRIPTION"
+#PROJECT_NAME           =
+
+# defined in 'config/config_dox_setup.dox'
+#    and 'config/config.h' as CONFIG_RELEASE_LEVEL
+#PROJECT_NUMBER         =
+
+#################################
+#
+# REMEMBER:  These relative path names are relative to
+#            the directory where this file is _invoked_
+#            not where it is stored!  This means for
+#            the sake of how paths are specified here
+#            that 'doxygen' must be _invoked_ from _this_
+#            directory!!!
+#
+OUTPUT_DIRECTORY = doc
+#################################
+USE_WINDOWS_ENCODING= YES # Windows users might want to change this
+#################################
+BRIEF_MEMBER_DESC      = YES
+REPEAT_BRIEF           = YES
+ABBREVIATE_BRIEF       = NO
+#################################
+FULL_PATH_NAMES        = YES
+STRIP_FROM_PATH        =
+STRIP_FROM_INC_PATH    =
+#################################
+CASE_SENSE_NAMES       = NO   # NO for Windows and CD-ROM distribs
+SHORT_NAMES            = NO   # YES for Windows and CD-ROM distribs
+JAVADOC_AUTOBRIEF      = YES
+DETAILS_AT_TOP         = YES  # Either way looks nice
+ALWAYS_DETAILED_SEC    = YES
+SEPARATE_MEMBER_PAGES  = NO
+#################################
+TAB_SIZE               = 4  # Only spaces are used in current code
+ENABLE_PREPROCESSING   = YES
+ALIASES                = 
+OPTIMIZE_OUTPUT_FOR_C  = YES
+########################################################################
+#
+# --- BUILD RELATED OPTIONS ---
+#
+EXTRACT_ALL            = YES
+EXTRACT_STATIC         = YES
+HIDE_UNDOC_MEMBERS     = NO
+HIDE_IN_BODY_DOCS      = NO
+INTERNAL_DOCS          = YES
+SHOW_INCLUDE_FILES     = YES
+SORT_MEMBER_DOCS       = NO
+SORT_BRIEF_DOCS        = YES
+#################################
+GENERATE_DEPRECATEDLIST= YES
+GENERATE_TODOLIST      = YES
+GENERATE_TESTLIST      = YES
+GENERATE_BUGLIST       = YES
+#################################
+# MAX_INITIALIZER_LINES  =     # Leave as default value
+SHOW_USED_FILES        = YES
+SHOW_DIRECTORIES       = YES
+########################################################################
+#
+# --- OPTIONS RELATED TO WARNINGS AND PROGRESS MESSAGES ---
+#
+QUIET                  = YES
+WARNINGS               = YES
+WARN_IF_UNDOCUMENTED   = YES # Overridden by EXTRACT_ALL
+WARN_IF_DOC_ERROR      = YES
+WARN_NO_PARAMDOC       = YES
+# WARN_FROMAT          =     # Leave as the default vaule
+# WARN_LOGFILE         =     # Leave as standard error output
+########################################################################
+#
+# --- INPUT RELATED OPTIONS ---
+#
+# File names to process and extract documentation
+#
+
+@INCLUDE = config/config_dox_setup.dox
+@INCLUDE = config/config_roster_c.dox
+@INCLUDE = config/config_roster_h.dox
+@INCLUDE = config/config_roster_jni_c.dox
+@INCLUDE = config/config_roster_jni_h.dox
+@INCLUDE = config/config_roster_jni_java.dox
+@INCLUDE = config/config_roster_test_java.dox
+@INCLUDE = config/config_roster_sh.dox
+
+
+#################################
+# FILE_PATTERNS        =     # Explicitly specify files with INPUT=
+# FILE_VERSION_FILTER  = svnstat.sh # Per doc recommendation
+RECURSIVE              = NO
+#################################
+EXCLUDE                =
+EXCLUDE_SYMLINKS       = NO
+EXCLUDE_PATTERNS       =
+#################################
+#
+# Comment out INPUT_FILTER for
+# faster processing when working
+# _only_ on source code.  This
+# cuts off a good amount of
+# processing time at the expense
+# of having garbage results for
+# shell script pages.  When done
+# with such work, re-enable this
+# parameter and rebuild all docs.
+#
+INPUT_FILTER           = dox_filter.sh
+
+# FILTER_PATTERNS      =
+FILTER_SOURCE_FILES    = YES
+########################################################################
+#
+# --- SOURCE BROWSER RELATED OPTIONS ---
+#
+SOURCE_BROWSER         = YES
+INLINE_SOURCES         = NO
+STRIP_CODE_COMMENTS    = NO
+REFERENCED_BY_RELATION = YES
+REFERENCES_RELATION    = YES
+########################################################################
+#
+# --- ALPHABETICAL INDEX OPTIONS ---
+#
+ALPHABETICAL_INDEX     = YES
+COLS_IN_ALPHA_INDEX    = 2
+########################################################################
+#
+# --- HTML RELATED OPTIONS ---
+#
+#GENERATE_HTML          = NO    # Enable if desired, via 'config.sh'
+HTML_OUTPUT            = html
+HTML_FILE_EXTENSION    = .html
+# HTML_HEADER          =
+# HTML_FOOTER          =
+# HTML_STYLESHEET      =
+HTML_ALIGN_MEMBERS     = YES
+GENERATE_HTMLHELP      = YES  # Windows users will want to change this
+CHM_FILE               = doc/bootjvm.chm
+# HHC_LOCATION         =      # Windows users _may_ want to change this
+# GENERATE_CHI         =      # Windows users _may_ want to change this
+# BINARY_TOC           =      # Windows users _may_ want to change this
+TOC_EXPAND             = YES
+# ENUM_VALUES_PER_LINE =
+DISABLE_INDEX          = NO
+########################################################################
+#
+# --- LATEX RELATED OPTIONS ---
+#
+#GENERATE_LATEX         = NO   # Enable if desired, via 'config.sh'
+LATEX_OUTPUT           = latex
+# LATEX_CMD_NAME       =
+# MAKEINDEX_CMD_NAME   =
+COMPACT_LATEX          = YES
+# PAPER_TYPE           =
+# EXTRA_PACKAGES       =
+# LATEX_HEADER         =
+# PDF_HYPERLINKS         = YES  # Enable if PDF browsing desired
+# USE_PDFLATEX           = YES  # Enable if PDF output desired
+LATEX_BATCHMODE        = YES
+LATEX_HIDE_INDICES     = YES
+########################################################################
+#
+# --- RTF RELATED OPTIONS ---
+#
+#GENERATE_RTF           = NO    # Enable if desired, via 'config.sh'
+RTF_OUTPUT             = rtf
+COMPACT_RTF            = YES
+RTF_HYPERLINKS         = YES
+# RTF_STYLESHEET_FILE  =
+# RTF_EXTENSIONS_FILE  =
+########################################################################
+#
+# --- MAN PAGE RELATED OPTIONS ---
+#
+#GENERATE_MAN           = NO    # Enable if desired, via 'config.sh'
+MAN_OUTPUT             = man
+MAN_EXTENSION          = .3
+MAN_LINKS              = YES
+########################################################################
+#
+# --- XML RELATED OPTIONS ---
+#
+#GENERATE_XML           = NO    # Enable if desired, via 'config.sh'
+XML_OUTPUT             = xml
+# XML_SCHEMA           =
+# XML_DTD              =
+XML_PROGRAMLISTING     = YES
+########################################################################
+#
+# --- PREPROCESSOR RELATED OPTIONS ---
+#
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = NO
+SEARCH_INCLUDES        = YES
+INCLUDE_PATH           = jvm/src \
+                         jvm/include \
+                         config \
+                         jni/src/harmony/generic/0.0/src  \
+                         jni/src/harmony/generic/0.0/include
+
+PREDEFINED             = I_AM_EXIT_C=nonnull \
+                         I_AM_JRTYPES_C=nonnull \
+                         I_AM_JVMCFG_C=nonnull \
+                         I_AM_STDIO_C=nonnull \
+\
+                         CONFIG_HEAP_TYPE_SIMPLE \
+                         CONFIG_HEAP_TYPE_BIMODAL \
+                         CONFIG_HEAP_TYPE_OTHER \
+\
+                         CONFIG_GC_TYPE_STUB \
+                         CONFIG_GC_TYPE_OTHER \
+
+# EXPAND_AS_DEFINED    =
+SKIP_FUNCTION_MACROS   = NO
+########################################################################
+#
+# --- EXTERNAL REFERENCE OPTIONS ---
+#
+# TAGFILES             =
+# GENERATE_TAGFILE     = doc/bootjvm.tag
+EXTERNAL_GROUPS        = YES
+########################################################################
+#
+# --- SEARCH ENGINE OPTIONS ---
+#
+SEARCHENGINE           = NO
+########################################################################
+#
+# Directives not applicable to this project:
+#
+# INLINE_INHERITED_MEMB
+# MULTILINE_CPP_IS_BRIEF
+# INHERIT_DOCS
+# DISTRIBUTE_GROUP_DOC
+# OPTIMIZE_OUTPUT_FOR_JAVA
+# EXTRACT_PRIVATE
+# EXTRACT_LOCAL_CLASSES
+# EXTRACT_LOCAL_METHODS
+# HIDE_UNDOC_CLASSES
+# HIDE_FRIEND_COMPOUNDS
+# INLINE_INFO
+# EXAMPLE_PATH
+# EXAMPLE_RECURSIVE
+# EXAMPLE_PATTERNS
+# IMAGE_PATH
+# VERBATIM_HEADERS
+# USE_HTAGS
+# IGNORE_PREFIX
+# GENERATE_TREEVIEW
+# TREEVIEW_WIDTH
+# ALLEXTERNALS
+# PERL_PATH
+# CLASS_DIAGRAMS
+#
+# ... \todo TODO:  Someone might want to get graphing working, but
+#                  remember that C++ functionality is not applicable:
+# HAVE_DOT
+# CLASS_GRAPH
+# COLLABORATION_GRAPH
+# GROUP_GRAPHS
+# UML_LOOK
+# TEMPLATE_RELATIONS
+# HIDE_UNDOC_RELATIONS
+# INCLUDE_GRAPH
+# INCLUDED_BY_GRAPH
+# CALL_GRAPH
+# GRAPHICAL_HIERARCHY
+# DIRECTORY_GRAPH
+# DOT_IMAGE_FORMAT
+# DOT_PATH
+# DOTFILE DIRS
+# MAX_DOT_GRAPH_HEIGHT
+# MAX_DOT_GRAPH_DEPTH
+# MAX_DOT_GRAPH_WIDTH
+# TOD_TRANSPARENT
+# DOT_MULTI_TARGETS
+# GENERATE_LEGEND
+# DOT_CLEANUP
+########################################################################
+#
+# EOF

Added: incubator/harmony/enhanced/trunk/sandbox/contribs/bootjvm/bootJVM/build.sh
URL: http://svn.apache.org/viewcvs/incubator/harmony/enhanced/trunk/sandbox/contribs/bootjvm/bootJVM/build.sh?rev=307257&view=auto
==============================================================================
--- incubator/harmony/enhanced/trunk/sandbox/contribs/bootjvm/bootJVM/build.sh (added)
+++ incubator/harmony/enhanced/trunk/sandbox/contribs/bootjvm/bootJVM/build.sh Fri Oct  7 21:27:56 2005
@@ -0,0 +1,87 @@
+#!/bin/sh
+#
+#!
+# @file /home/dlydick/harmony/bootJVM/build.sh
+#
+# @brief Build Boot JVM.
+#
+# Build a component of the project.  This either means to
+# compile source code and either archive or link it, or
+# to generate documentation.
+#
+# The main body of logic for this script is found in
+# @link common.sh common.sh@endlink.
+#
+# @see @link ./clean.sh ./clean.sh@endlink
+#
+# @see @link ./common.sh ./common.sh@endlink
+#
+# @see @link jvm/build.sh jvm/build.sh@endlink
+#
+# @see @link libjvm/build.sh libjvm/build.sh@endlink
+#
+# @see @link main/build.sh main/build.sh@endlink
+#
+# @see @link test/build.sh test/build.sh@endlink
+#
+# @see @link jni/src/harmony/generic/0.0/build.sh
+#            jni/src/harmony/generic/0.0/build.sh@endlink
+#
+#
+# @todo  The entire project should also have 'gmake' support.  It
+#        would be a simple thing to add/change the 'config/*' roster
+#        files with @link config.sh config.sh@endlink to support this.
+#
+# @todo  A Windows .BAT version of this script needs to be written
+#
+#
+# @section Control
+#
+# \$URL: https://svn.apache.org/path/name/build.sh $ \$Id: build.sh 0 09/28/2005 dlydick $
+#
+# Copyright 2005 The Apache Software Foundation
+# or its licensors, as applicable.
+#
+# Licensed under the Apache License, Version 2.0 ("the License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+# either express or implied.
+#
+# See the License for the specific language governing permissions
+# and limitations under the License.
+#
+# @version \$LastChangedRevision: 0 $
+#
+# @date \$LastChangedDate: 09/28/2005 $
+#
+# @author \$LastChangedBy: dlydick $
+#         Original code contributed by Daniel Lydick on 09/28/2005.
+#
+# @section Reference
+#
+#/ /* 
+# (Use  #! and #/ with dox_filter.sh to fool Doxygen into
+# parsing this non-source text file for the documentation set.
+# Use the above open comment to force termination of parsing
+# since it is not a Doxygen-style 'C' comment.)
+#
+#
+###################################################################
+#
+# Invoke common code.
+#
+. common.sh
+
+###################################################################
+#
+# Done.
+#
+
+#
+# EOF

Propchange: incubator/harmony/enhanced/trunk/sandbox/contribs/bootjvm/bootJVM/build.sh
------------------------------------------------------------------------------
    svn:executable = *

Added: incubator/harmony/enhanced/trunk/sandbox/contribs/bootjvm/bootJVM/clean.sh
URL: http://svn.apache.org/viewcvs/incubator/harmony/enhanced/trunk/sandbox/contribs/bootjvm/bootJVM/clean.sh?rev=307257&view=auto
==============================================================================
--- incubator/harmony/enhanced/trunk/sandbox/contribs/bootjvm/bootJVM/clean.sh (added)
+++ incubator/harmony/enhanced/trunk/sandbox/contribs/bootjvm/bootJVM/clean.sh Fri Oct  7 21:27:56 2005
@@ -0,0 +1,83 @@
+#!/bin/sh
+#
+#!
+# @file /home/dlydick/harmony/bootJVM/clean.sh
+#
+# @brief Remove build of Boot JVM.
+#
+# Remove a build of a component of the project.  This either means to
+# remove compiled object code and either remove a static library
+# archive file or a linked binary, or to remove generated documentation.
+#
+# The main body of logic for this script is found in
+# @link common.sh common.sh@endlink.
+#
+# @see @link ./build.sh ./build.sh@endlink
+#
+# @see @link ./common.sh ./common.sh@endlink
+#
+# @see @link jvm/clean.sh jvm/clean.sh@endlink
+#
+# @see @link libjvm/clean.sh libjvm/clean.sh@endlink
+#
+# @see @link main/clean.sh main/clean.sh@endlink
+#
+# @see @link test/clean.sh test/clean.sh@endlink
+#
+# @see @link jni/src/harmony/generic/0.0/clean.sh
+#            jni/src/harmony/generic/0.0/clean.sh@endlink
+#
+#
+# @todo  A Windows .BAT version of this script needs to be written
+#
+#
+# @section Control
+#
+# \$URL: https://svn.apache.org/path/name/clean.sh $ \$Id: clean.sh 0 09/28/2005 dlydick $
+#
+# Copyright 2005 The Apache Software Foundation
+# or its licensors, as applicable.
+#
+# Licensed under the Apache License, Version 2.0 ("the License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+# either express or implied.
+#
+# See the License for the specific language governing permissions
+# and limitations under the License.
+#
+# @version \$LastChangedRevision: 0 $
+#
+# @date \$LastChangedDate: 09/28/2005 $
+#
+# @author \$LastChangedBy: dlydick $
+#         Original code contributed by Daniel Lydick on 09/28/2005.
+#
+# @section Reference
+#
+#/ /* 
+# (Use  #! and #/ with dox_filter.sh to fool Doxygen into
+# parsing this non-source text file for the documentation set.
+# Use the above open comment to force termination of parsing
+# since it is not a Doxygen-style 'C' comment.)
+#
+#
+###################################################################
+#
+# Invoke common code.
+#
+. common.sh
+
+###################################################################
+#
+# Done.
+#
+
+#
+# EOF

Propchange: incubator/harmony/enhanced/trunk/sandbox/contribs/bootjvm/bootJVM/clean.sh
------------------------------------------------------------------------------
    svn:executable = *