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 + + + + + Linux + + + + +

+ 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:

@@ -92,24 +170,28 @@

- 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:

@@ -117,18 +199,22 @@

- 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.

@@ -137,29 +223,29 @@

- 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.

@@ -168,42 +254,53 @@ $ ant -

- 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

+

+ + -Dhttp.proxyPort=']]> - -

- 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)

+ +unzip <path_to_vm_zip> -d ../.. (on Windows) +tar xzf <path_to_vm_tarball> --directory ../.. (on Linux) + + +

- Once you have a VM installed, you can run the tests very easily : + Once you have a VM installed, you can run the tests:

$ ant test

- 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.

@@ -212,74 +309,126 @@

- 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.

$ cp drlvm.properties.example drlvm.properties -

- 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: +

C:...\trunk\working_vm\build> set CXX=msvc - +

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.

-On Linux : +On Linux: $ sh build.sh update -On Windows : +On Windows: C:...\trunk\working_vm\build>build.bat update

- Once we have obtained our dependencies, we can proceed with the build : -

+ When you have obtained the dependencies, you can proceed + with the build:

+ -On Linux : +On Linux: $ sh build.sh -On Windows : +On Windows: C:...\trunk\working_vm\build>build.bat

- and when complete, with the tests : + To complete the operation, run the following tests:

-On Linux : +On Linux: $ sh build.sh test -On Windows : +On Windows: C:...\trunk\working_vm\build>build.bat test -

- 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 -

+ At this point, the DRLVM build is complete. A full JRE is in the + deploy/jre subdirectory of the build + directory. +

$ cd deploy/jre/bin @@ -296,21 +445,34 @@

- 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:

+ +> jre\bin\java -showversion -jar helloworld.jar +java version 1.5 (subset) +(c) Copyright 1991, 2006 The Apache Software Foundation or its licensors, as applicable. +Hello world! + +