======================================
         Apache Harmony DRLVM
======================================

DRLVM is one of the virtual machines of the Apache Harmony project. 
It contains: 
 
    - VM (VM Core)
    - GC
    - JIT
    - Bytecode Verifier 
    - Class Libraries (Kernel Classes only)
    - OS Layer

See http://wiki.apache.org/harmony for a definition of these components.

The currently supported configurations are Windows* x86, x86_64 and Linux* x86, x86_64, ia64.

  
1. DRLVM SOURCE TREE CONTENTS
-----------------------------
 
This source tree consists of the source files, the building scripts,
and the tests source files for integrity testing of the DRLVM.

The structure is as follows: 

 <EXTRACT_DIR>
        |
        +---make           - Files required to build the contribution
        |      
        \---vm             - VM source files
            |
            +- doc         - DRLVM Developer's Guide and Getting Started guide
            |
            +- em          - Execution Manager component responsible for dynamic optimization
            |
            +- gc_cc       - Stop-the-world adaptive copying/slide compacting garbage
            |                collector with dynamic algorithm switching
            |
            +- gc_gen      - Generational garbage collector
            |
            +- include     - Set of header files containing external specification
            |                and inter-component interfaces
            |
            +- interpreter - Interpreter component
            |
            +- jitrino     - Just-in-time Compiler component
            |
            +- port        - OS and platform porting layer component which, together with
            |                APR, provides an unified interface to low-level system routines 
            |                across different platforms
            |
            +- tests       - Tests source files
            |
            +- thread      - Thread manager (TM) library aimed to provide threading capabilities 
            |                for Java virtual machines
            |
            +- vmcore      - Core component responsible for class loading and resolution,
            |                kernel classes, JNI and JVMTI support, stack support, threading
            |                support, exception handling, verifier, and a set of other services
            |                and utilities
            |
            +- vmi         - Component responsible for compatibility with the Harmony class
            |                libraries 
            |
            \- vmstart     - Partial implementation of the component manager for handling 
                             VM components as pluggable modules 
 
 
2. TOOLS AND ENVIRONMENT VARIABLES REQUIRED FOR THE BUILD
---------------------------------------------------------
In order to build the source code, it is necessary to configure the following tools 
in the user environment. That is, the working environment should be such that the PATH 
environment variable contains all of the directories where the executables of
the tools listed below are located and that all of those executables can be 
successfully invoked from the command line. On Windows, this typically implies
that the build is started from Visual Studio Command Prompt console window.


* C++ compiler - on Windows, the Microsoft(R) 32-bit C/C++ Compiler and on
               Linux, the GNU project C/C++ Compiler.

* Java compiler - By default, the build scripts are setup to use the Eclipse
                  compiler (ECJ). The ECJ needs to be in the Ant class path
                  to execute correctly.
                  
* Apache Ant - A Java based build tool. See http://ant.apache.org/.
               It's suggested that the ANT_OPTS environment variable be set
               to a value of "-Xms256M -Xmx512M" while running the build scripts
               for Harmony.

* Doxygen - the open source documentation system for a variety of programming 
            languages including C, C++ and Java.
            See http://www.doxygen.org
            

The top-level Ant script <EXTRACT_DIR>/build.xml has a default target 
which builds both the Java source and C++ source files. It is expected
therefore that, at a minimum, a C++ compiler and a Java compiler be available.
Doxygen is only necessary if generation of HTML documentation from the
source code is to be carried out by invoking Ant with the "doc" target on
the <EXTRACT_DIR>/build.xml script. As a convenience, pre-generated
HTML files are already stored in subversion.

2.1 DRLVM DEPENDENCIES
----------------------
The DRLVM depends on common_resources module of Apache Harmony for managing 
external dependencies. Further, it needs either HDK or Harmony class library 
to build against and comprise a complete workable JRE.
You can separately obtain those modules, refer to Getting Started page on 
Apache Harmony site [http://harmony.apache.org/quickhelp_contributors.html].
 
Also, there are external resources required for building DRLVM: 
zlib, apr-1.3.8, log4cxx, cpptasks-1.b04, etc. 
This list can change as DRLVM is being developed, so the best way to resolve 
external dependencies is to let the build download them:
$ ant fetch-depends

By default DRLVM assumes federated build layout, as described on the 
aforementioned Getting Started page. That is, common_resources and classlib 
modules reside in the same parent directory as DRLVM's <EXTRACT_DIR>, 
w/o extra "trunk" levels inside. 
You may override default locations via the following build arguments:
-Dcommon.resources.loc=<common_resources-location>
-Dhy.hdk=<unpacked-HDK-location>
-Dexternal.dep.CLASSLIB.loc=<classlib-location>
For example, run this command to check if all build prerequisites are met:
$ ant -Dcommon.resources.loc=<path> -Dhy.hdk=<path> check-depends

3. BUILDING VM
--------------

The simplest way to get started is to change directory into <EXTRACT_DIR> and
then type "ant" to run Apache Ant against the default target of the build.xml
file. Provided that the required compilers are available and configured properly, 
Ant will proceed to compile all the DRLVM source code.
Build mode (release/debug) is controlled with "hy.cfg" property, default is debug.
E.g. type to build in release mode:
$ ant -Dhy.cfg=release

The build produces a set of .jar files, native libraries, and
support files that constitute the executable JRE. Also, it imports required
supplementary binaries from the pre-built classlib. The complete workable JRE 
is placed in the following directory tree structure:

./build/${OS}_${CPU_arch}_${CXX}_${BUILD_CFG}
       \---deploy
             |
             \---jdk
                  |
                  \---jre
                  |     |
                  |     +---bin           <- classlibrary native code & launcher
                  |     |   |
                  |     |   +---default   <- DRLVM binaries
                  |     |
                  |     \---lib
                  |         |
                  |         +---boot      <- common JARs for bootclasspath
                  |         | 
                  |         +---ext       <- extensions directory
                  |         |
                  |         \---security
                  |
                  +---include             <- JNI & JVMTI headers

              
You can now run DRLVM on the command line or under Eclipse*. For details on 
how to run the VM under Eclipse*, see Getting Started with DRLVM, 
[http://harmony.apache.org/subcomponents/drlvm/getting_started.html].  

 3.1 Build the selected components. 
     
If you're developing only particular component of DRLVM, it is possible to 
optimize recompilation time and re-build just that component invoking 
particular ant script. For example, do clean rebuild of GCv5:
$ ant -f make/vm/gc_gen.xml clean build
Another example, perform incremental build of Jitrino:
$ ant -f make/vm/jitrino.xml

However this way works only if you did not modify any of component's dependencies. 
E.g. if you modified encoder or vmcore while developing Jitrino, you'd want to rebuild 
Jitrino and everything it depends upon:
$ ant jitrino

4. RUNNING DRLVM WITH EXTERNAL CLASS LIBRARIES
----------------------------------------------
 
To run DRLVM with third-party external class libraries, do the following:

1. Check that these class libraries comply with the kernel classes interface 
   and the VMI interfaces, see the description in the directory
   <EXTRACT_DIR>/Harmony/vm/vmcore/src/kernel_classes. 

2. Add external native dynamic libraries (*.dll or *.so files) to the system path or copy 
   the files into the <EXTRACT_DIR>/deploy/jre/bin directory. 

3. Add external library class directories or .jar files into the -Xbootclasspath option. 

Example:
$ java -Xbootclasspath/p:c:\external_library\lib\classes.jar MyApp
 

5. BUILDING AND RUNNING TESTS
-----------------------------

DRLVM provides a fair amount of functional and unit tests, you can build and run 
them all with the following command:
$ ant smoke.test kernel.test cunit.test jvmti.test reg.test hut.test ehwa.test 
The test binaries and run results are placed in "tests" directory tree
nearby "deploy" one:
./build/${OS}_${CPU_arch}_${CXX}_${BUILD_CFG}/tests

For convenience, build also provides aggregative test targets, which run most of the 
tests with a single command:
$ ant test
$ ant test2

Common flags supported by all test suites:
* test.mode - list of predefined VM modes to test (see make/test.properties). 
              "jit,opt,int" by default. Does not affect HUT, cunit and reg tests 
* test.case - name of a single specific test to run
* test.jvm.exe - location of external JVM to be tested 
 

6. TROUBLESHOOTING
-------------------
 
For build troubleshooting information, refer to the Wiki page: 
http://wiki.apache.org/harmony/DrlvmBuildTroubleshooting


7. TODO
--------

For information on TODO issues, refer to the Wiki page:
http://wiki.apache.org/harmony/TODO_List_for_DRLVM