README.txt

   1 ======================================
   2          Apache Harmony DRLVM
   3 ======================================
   4
   5 DRLVM is one of the virtual machines of the Apache Harmony project.
   6 It contains:
   7
   8     - VM (VM Core)
   9     - GC
  10     - JIT
  11     - Bytecode Verifier
  12     - Class Libraries (Kernel Classes only)
  13     - OS Layer
  14
  15 See http://wiki.apache.org/harmony for a definition of these components.
  16
  17 The currently supported configurations are Windows* x86, x86_64 and Linux* x86, x86_64, ia64.
  18
  19
  20 1. DRLVM SOURCE TREE CONTENTS
  21 -----------------------------
  22
  23 This source tree consists of the source files, the building scripts,
  24 and the tests source files for integrity testing of the DRLVM.
  25
  26 The structure is as follows:
  27
  28  <EXTRACT_DIR>
  29         |
  30         +---make           - Files required to build the contribution
  31         |
  32         \---vm             - VM source files
  33             |
  34             +- doc         - DRLVM Developer's Guide and Getting Started guide
  35             |
  36             +- em          - Execution Manager component responsible for dynamic optimization
  37             |
  38             +- gc_cc       - Stop-the-world adaptive copying/slide compacting garbage
  39             |                collector with dynamic algorithm switching
  40             |
  41             +- gc_gen      - Generational garbage collector
  42             |
  43             +- include     - Set of header files containing external specification
  44             |                and inter-component interfaces
  45             |
  46             +- interpreter - Interpreter component
  47             |
  48             +- jitrino     - Just-in-time Compiler component
  49             |
  50             +- port        - OS and platform porting layer component which, together with
  51             |                APR, provides an unified interface to low-level system routines
  52             |                across different platforms
  53             |
  54             +- tests       - Tests source files
  55             |
  56             +- thread      - Thread manager (TM) library aimed to provide threading capabilities
  57             |                for Java virtual machines
  58             |
  59             +- vmcore      - Core component responsible for class loading and resolution,
  60             |                kernel classes, JNI and JVMTI support, stack support, threading
  61             |                support, exception handling, verifier, and a set of other services
  62             |                and utilities
  63             |
  64             +- vmi         - Component responsible for compatibility with the Harmony class
  65             |                libraries
  66             |
  67             \- vmstart     - Partial implementation of the component manager for handling
  68                              VM components as pluggable modules
  69
  70
  71 2. TOOLS AND ENVIRONMENT VARIABLES REQUIRED FOR THE BUILD
  72 ---------------------------------------------------------
  73 In order to build the source code, it is necessary to configure the following tools
  74 in the user environment. That is, the working environment should be such that the PATH
  75 environment variable contains all of the directories where the executables of
  76 the tools listed below are located and that all of those executables can be
  77 successfully invoked from the command line. On Windows, this typically implies
  78 that the build is started from Visual Studio Command Prompt console window.
  79
  80
  81 * C++ compiler - on Windows, the Microsoft(R) 32-bit C/C++ Compiler and on
  82                Linux, the GNU project C/C++ Compiler.
  83
  84 * Java compiler - By default, the build scripts are setup to use the Eclipse
  85                   compiler (ECJ). The ECJ needs to be in the Ant class path
  86                   to execute correctly.
  87
  88 * Apache Ant - A Java based build tool. See http://ant.apache.org/.
  89                It's suggested that the ANT_OPTS environment variable be set
  90                to a value of "-Xms256M -Xmx512M" while running the build scripts
  91                for Harmony.
  92
  93 * Doxygen - the open source documentation system for a variety of programming
  94             languages including C, C++ and Java.
  95             See http://www.doxygen.org
  96
  97
  98 The top-level Ant script <EXTRACT_DIR>/build.xml has a default target
  99 which builds both the Java source and C++ source files. It is expected
 100 therefore that, at a minimum, a C++ compiler and a Java compiler be available.
 101 Doxygen is only necessary if generation of HTML documentation from the
 102 source code is to be carried out by invoking Ant with the "doc" target on
 103 the <EXTRACT_DIR>/build.xml script. As a convenience, pre-generated
 104 HTML files are already stored in subversion.
 105
 106 2.1 DRLVM DEPENDENCIES
 107 ----------------------
 108 The DRLVM depends on common_resources module of Apache Harmony for managing
 109 external dependencies. Further, it needs either HDK or Harmony class library
 110 to build against and comprise a complete workable JRE.
 111 You can separately obtain those modules, refer to Getting Started page on
 112 Apache Harmony site [http://harmony.apache.org/quickhelp_contributors.html].
 113
 114 Also, there are external resources required for building DRLVM:
 115 zlib, apr-1.3.8, log4cxx, cpptasks-1.b04, etc.
 116 This list can change as DRLVM is being developed, so the best way to resolve
 117 external dependencies is to let the build download them:
 118 $ ant fetch-depends
 119
 120 By default DRLVM assumes federated build layout, as described on the
 121 aforementioned Getting Started page. That is, common_resources and classlib
 122 modules reside in the same parent directory as DRLVM's <EXTRACT_DIR>,
 123 w/o extra "trunk" levels inside.
 124 You may override default locations via the following build arguments:
 125 -Dcommon.resources.loc=<common_resources-location>
 126 -Dhy.hdk=<unpacked-HDK-location>
 127 -Dexternal.dep.CLASSLIB.loc=<classlib-location>
 128 For example, run this command to check if all build prerequisites are met:
 129 $ ant -Dcommon.resources.loc=<path> -Dhy.hdk=<path> check-depends
 130
 131 3. BUILDING VM
 132 --------------
 133
 134 The simplest way to get started is to change directory into <EXTRACT_DIR> and
 135 then type "ant" to run Apache Ant against the default target of the build.xml
 136 file. Provided that the required compilers are available and configured properly,
 137 Ant will proceed to compile all the DRLVM source code.
 138 Build mode (release/debug) is controlled with "hy.cfg" property, default is debug.
 139 E.g. type to build in release mode:
 140 $ ant -Dhy.cfg=release
 141
 142 The build produces a set of .jar files, native libraries, and
 143 support files that constitute the executable JRE. Also, it imports required
 144 supplementary binaries from the pre-built classlib. The complete workable JRE
 145 is placed in the following directory tree structure:
 146
 147 ./build/${OS}_${CPU_arch}_${CXX}_${BUILD_CFG}
 148        \---deploy
 149              |
 150              \---jdk
 151                   |
 152                   \---jre
 153                   |     |
 154                   |     +---bin           <- classlibrary native code & launcher
 155                   |     |   |
 156                   |     |   +---default   <- DRLVM binaries
 157                   |     |
 158                   |     \---lib
 159                   |         |
 160                   |         +---boot      <- common JARs for bootclasspath
 161                   |         |
 162                   |         +---ext       <- extensions directory
 163                   |         |
 164                   |         \---security
 165                   |
 166                   +---include             <- JNI & JVMTI headers
 167
 168
 169 You can now run DRLVM on the command line or under Eclipse*. For details on
 170 how to run the VM under Eclipse*, see Getting Started with DRLVM,
 171 [http://harmony.apache.org/subcomponents/drlvm/getting_started.html].
 172
 173  3.1 Build the selected components.
 174
 175 If you're developing only particular component of DRLVM, it is possible to
 176 optimize recompilation time and re-build just that component invoking
 177 particular ant script. For example, do clean rebuild of GCv5:
 178 $ ant -f make/vm/gc_gen.xml clean build
 179 Another example, perform incremental build of Jitrino:
 180 $ ant -f make/vm/jitrino.xml
 181
 182 However this way works only if you did not modify any of component's dependencies.
 183 E.g. if you modified encoder or vmcore while developing Jitrino, you'd want to rebuild
 184 Jitrino and everything it depends upon:
 185 $ ant jitrino
 186
 187 4. RUNNING DRLVM WITH EXTERNAL CLASS LIBRARIES
 188 ----------------------------------------------
 189
 190 To run DRLVM with third-party external class libraries, do the following:
 191
 192 1. Check that these class libraries comply with the kernel classes interface
 193    and the VMI interfaces, see the description in the directory
 194    <EXTRACT_DIR>/Harmony/vm/vmcore/src/kernel_classes.
 195
 196 2. Add external native dynamic libraries (*.dll or *.so files) to the system path or copy
 197    the files into the <EXTRACT_DIR>/deploy/jre/bin directory.
 198
 199 3. Add external library class directories or .jar files into the -Xbootclasspath option.
 200
 201 Example:
 202 $ java -Xbootclasspath/p:c:\external_library\lib\classes.jar MyApp
 203
 204
 205 5. BUILDING AND RUNNING TESTS
 206 -----------------------------
 207
 208 DRLVM provides a fair amount of functional and unit tests, you can build and run
 209 them all with the following command:
 210 $ ant smoke.test kernel.test cunit.test jvmti.test reg.test hut.test ehwa.test
 211 The test binaries and run results are placed in "tests" directory tree
 212 nearby "deploy" one:
 213 ./build/${OS}_${CPU_arch}_${CXX}_${BUILD_CFG}/tests
 214
 215 For convenience, build also provides aggregative test targets, which run most of the
 216 tests with a single command:
 217 $ ant test
 218 $ ant test2
 219
 220 Common flags supported by all test suites:
 221 * test.mode - list of predefined VM modes to test (see make/test.properties).
 222               "jit,opt,int" by default. Does not affect HUT, cunit and reg tests
 223 * test.case - name of a single specific test to run
 224 * test.jvm.exe - location of external JVM to be tested
 225
 226
 227 6. TROUBLESHOOTING
 228 -------------------
 229
 230 For build troubleshooting information, refer to the Wiki page:
 231 http://wiki.apache.org/harmony/DrlvmBuildTroubleshooting
 232
 233
 234 7. TODO
 235 --------
 236
 237 For information on TODO issues, refer to the Wiki page:
 238 http://wiki.apache.org/harmony/TODO_List_for_DRLVM