Index: quickhelp_contributors.xml =================================================================== --- quickhelp_contributors.xml (revision 454321) +++ quickhelp_contributors.xml (working copy) @@ -28,63 +28,141 @@
+ The Harmony class library code is a subset of the Java(tm) SE 1.5 APIs currently + being developed in the + Apache Harmony project + . + This document explains how to get configured to build and + work with the Apache Harmony source code. +
-- This document explains how to get configured to build and - work with the Apache Harmony source code. -
-- Basic prequisites for working with Apache Harmony are : -
- ++ Basic prerequisites for working with Apache Harmony are: +
+ ++ The other prerequisites for building Harmony differ by the platform: +
+ + + Windows + ++ Additional software and libraries that the building system + can download from the Internet are the following: +
+Note
++ The PATH environment variable must include the location of SVN tool set. + Run SVN manually at least once prior to build, since it may ask to + accept the certificates from Apache site in an interactive manner. +
-- The other prerequistes for building Harmony differ by platform : -
++ Alternatively, you can download these resources prior to building DRLVM, + unpack these, and specify the resulting location by using the + environment variables, as described in the + + README file, step 3.3.1. In this + + README file you can find instructions on how to point to local + versions instead of making the build download new ones from the net. +
- Linux - -- Linux deps go here -
- - Windows - -- Windows deps go here - -
- The remaining instructions assume the above are installed on your platform. -
- The Harmony codebase is divided into many separate parts. To create a working - JRE, you'll need the class library and a virtual machine. Currently, the - easiest way to do this is uing the "federated build" tree and then working - within the class library directory and the VM directory as you choose. - Currently, the federated build uses the DRLVM virtuaal machine. + The Harmony codebase is divided into many separate parts. To create + a working JRE, you need a class library and a virtual machine. To + obtain these tools, use the federated build tree and then work + within the class library directory and the VM directory as you choose. + Currently, the federated build uses the DRLVM virtual machine.
- First, checkout the federated build : + First, checkout the federated build:
- This will checkout a directory structure that contains a working_classlib
- directory, which after the next step will be the checkout of the classlib SVN tree
- and working_vm, which after the next step will be the checkout
+ The given command will checkout a directory structure that
+ contains working_classlib and working_vm
+ directories. After the next step working_classlib
+ will be the checkout of the class library SVN tree
+ and working_vm will be the checkout
of the DRLVM SVN tree.
- Note that if you type "ant" in this directory, you will checkout, build and - package snapshots of the JRE and HDK. However, this isn't a convenient - way to work for a developer, so please continue with the next steps. -
+Note
+
+ If you type ant in this directory, you will checkout,
+ build, and package snapshots of the JRE and HDK. However, this way
+ is inconvenient for a developer, so please continue with the next steps.
+
- The federated build build.xml script contains a useful target
- created to help populate the source trees. To do so, just do the following in the
- root directory of the federated build :
+ To help populate the source trees, use the target located
+ in the federated build build.xml script.
+ Type the following command in the root directory of the
+ federated build:
- This will checkout classlib and DRLVM into the working_classlib and working_vm
- directories, respectively, at the same SVN version of the build.xml file. Please
- note that the source trees are large, and that a checkout can take a very long time.
- Also, not that due to limits of the Windows filesystem, if the root of the
- federated build is multiple levels deep in your filesystem, the very long paths within
- classlibrary might result in a SVN checkout failure on Windows. The solution is to move the
- tree upwards in your filesystem (or switch operating systems).
+ The given command will checkout class library and DRLVM into the
+ working_classlib and working_vm
+ directories respectively, at the same SVN version of the
+ build.xml file. The source trees are large,
+ therefore a checkout can take a very long time.
Note
++ If the root of the federated build is multiple levels deep in + your filesystem, the very long paths within class library might + result in a SVN checkout failure on Windows. The solution is to + move the tree upwards in your filesystem, or switch operating systems.
- Note
- that at any time going forward, you can bring either directory to current SVN
- revision simply by doing a svn update in either directory.
+ Any time going forward, you can bring any directory to current SVN
+ revision simply by doing svn update in any directory.
- These are full, valid checkouts of the classlibrary and DRLVM. Any modifications
- made to the SVN repository will be reflected in your tree after a svn update.
- If you are a project committer, you can make commits from within this tree - it's
- a normal SVN checkout.
+ The aforementioned commands are valid checkouts of the class library
+ and DRLVM. After executing svn update, your tree will
+ reflect any modifications made to the SVN repository. If you are a
+ project committer, you can make commits from within this tree, as it
+ is a normal SVN checkout.
- Now you should be ready to build the code. The DRLVM has a dependency on the - class library and also assembles a working JRE as part of it's build, so you should - build the classlibrary first. + Now you should be ready to build the code. First of all, you should + build the class library, since the DRLVM has a dependency on the + class library and also assembles a working JRE as part of its build.
Building the Class Library- For the first time you build, you'll want to - fetch all the classlib dependencies. If you don't, or if in the future a new - dependency is added, the build will tell you what to do, so you may have to do this - step periodically. + For the first time you build, you might want to fetch all the + class-library dependencies. If you do not, or if in the future a new + dependency is added, the build will tell you what to do, so that you + can do this step periodically.
- Note that if you are working from behind a firewall, you may need to configure - ant to use a proxy via the ANT_OPTS environment variable. For example -
- -
+ If you are working from behind a firewall, you may need to configure
+ ant to use a proxy via the ANT_OPTS
+ environment variable.
Example
+
+
+
- If the above succeeds, you now have built the Apache Harmony classlibrary, both - the Java code as well as the native code for your platform. To run the test suite, - you will first need a virtual machine. As the DRLVM isn't yet complete, - you can use the + + If the aforementioned command succeeds, build the Apache Harmony + class library, the Java and the native code for your platform. + To run the test suite, you need a virtual machine. As the DRLVM is + yet incomplete, you can use the - IBM J9 virtual machine generously made available for the project's development needs - by IBM under a non-open source, binary evaluation license. Please install according to - the instructions that accompany that VM. -
+ IBM J9 virtual machine generously made available for the project's + development needs by IBM under a non-open source, binary evaluation license. + To install the VM, follow the instructions that accompany that VM. + You can expand the class library code over the top of the Harmony directory (so that the 'jdk' + directories line-up) +- Once you have a VM installed, you can run the tests very easily : + Once you have a VM installed, you can run the tests:
- Which will run the full testsuite for the classlibrary. + The given command will run the full testsuite for the class library.
Building DRLVM
- Now that classlibrary is built, we can build the DRLVM, which will assemble a working
- JRE as well. To do this, return to the root of the federated build and switch into the
- working_vm directory. Then switch into DRLVM's build directory.
+ When the class library is built, you should build the DRLVM
+ assembling a working JRE as well. To build the DRLVM, return
+ to the root of the federated build and switch into the
+ working_vm directory. Then switch into DRLVM build
+ directory.
- The first thing we have to do is tell the DRLVM build where to find the class library.
- We can do this simply by renaming the file drlvm.properties.example in
- the DRLVM build directory to drlvm.properties. This file
- containes a property definition that tells DRLVM build to use the classlib in
- working_classlib. If you need to, you can override this on the command line
- if you want to point to another build of the classlib.
+ First of all, tell the DRLVM build where to find the class library:
+ rename the file drlvm.properties.example in the DRLVM
+ build directory to drlvm.properties.
+ This file containes a property definition that tells DRLVM build to
+ use the class library in working_classlib.
+ If you want to point to another build of the class library, override
+ the given file on the command line.
- If you are a windows user, note that you must be working from the Visual - Studio .NET Command Promt (you'll see it - it's installed with the Visual Studio mentioned - above). As of now, you cannot build from a Cygwin or other alternative shell. Also, you - will need to set the "CXX" environment variable to "msvc" to indicate to the build - which compiler is being used. Again, for windows only users : -
+Note
+
+ If you are a Windows user, you must work from the Visual
+ Studio .NET Command Prompt installed with the Visual Studio.
+ As for now, you cannot build from a Cygwin or other alternative shell.
+ Set the CXX environment variable to msvc
+ to indicate to the build used by the compiler:
+
You can switch between the different compilers and modes by using + the environment variables, as follows: +
+
| + Compiler + | ++ On Windows + | ++ On Linux + | +
|---|---|---|
| + MSVC compiler + | ++ set CXX=msvc + | ++ N/A + | +
| + Intel(R) compiler + | ++ set CXX=icl + | ++ export CXX=icc + | +
| + GCC compiler + | ++ N/A + | ++ export CXX=gcc + | +
- Now you are ready to build. To do so, we first fetch our dependencies. Please note that this - can take a long time. Be patient : + Now you are ready to build. To start the build, fetch the + dependencies. Note that this can take a long time.
- Once we have obtained our dependencies, we can proceed with the build : -
+ When you have obtained the dependencies, you can proceed + with the build: +- and when complete, with the tests : + To complete the operation, run the following tests:
- Note that the so-called "kernel" tests don't currently pass. If you get through the - "C Unit" and "Smoke" tests, you are doing ok. +
Note
+The kernel tests do not currently pass.
+ To succeed use C Unit and
+ Smoke tests.
- At this point, the DRLVM build is complete. There is a full JRE in the
- deploy/jre subdirectory of the build directory.
- You can simply
-
deploy/jre subdirectory of the build
+ directory.
+
- There are two ways developers use the code. Class library developers tend
- to install the IBM J9 VM in the working_classlib/deploy/jdk/jre
- so they can use it as a "known good" VM for unit testing. DRLVM developers
- tend to work with the result of the DRLVM build step, which is a JRE
- containing the DRLVM and the class library.
+ Developers refer to one of the two ways of using code. Class
+ library developers install the IBM J9 VM in the
+ working_classlib/deploy/jdk/jre, so they can use
+ it as a well-known VM for unit testing. To work with the class
+ library, refer to the
+ classlibrary
+ subcomponent. DRLVM developers work with the result of the
+ DRLVM build step, which is a JRE containing the DRLVM and the
+ class library. To work with the DRLVM, set
+ JAVA_HOME to the deploy/jre.
- To work with the classlibrary, please continue with the material found - in our classlibrary subcomponent. -
- -
- To work with the DRLVM, you can simple set JAVA_HOME to the deploy/jre
-
+ Ensure that the JAVA_HOME environment variable is unset, or pointing
+ to the Harmony/deploy/jdk/jre directory.
+
+ Run Java applications as usual, using the launcher in Harmony/deploy/jdk/jre/bin:
+