You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@harmony.apache.org by ge...@apache.org on 2005/10/08 06:29:29 UTC
svn commit: r307257 [2/24] - in
/incubator/harmony/enhanced/trunk/sandbox/contribs/bootjvm: ./ bootJVM/
bootJVM/jni/ bootJVM/jni/src/ bootJVM/jni/src/gnu/
bootJVM/jni/src/gnu/classpath/ bootJVM/jni/src/gnu/classpath/0.16/
bootJVM/jni/src/gnu/classpath/...
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 = *