Repositories
This section describes the OpenJDK repository terminology and naming scheme. It also includes minimal instructions to acquire the appropriate source as the basis for all OpenJDK contributions.
The JDK source is available from other locations, for example
src.zipfrom a full JDK distribution. However, OpenJDK contributions must use source from the Mercurial repositories since other source distributions may contain older code or code which differs due to licensing.
Operations which are performed repeatedly, such as creating changesets, merging, and pushing are described in Producing a Changeset.
- Terminology and Naming Scheme defines the nomenclature used by the OpenJDK project.
- Installing and Configuring Mercurial enumerates the required software, provides links for download, and describes basic installation and configuration.
- Cloning covers the procedure for obtaining private copies of source repositories.
This document assumes familiarity with the first two chapters of the main Mercurial documentation at http://hgbook.red-bean.com.
Terminology and Naming Scheme
The OpenJDK code base is stored in multiple Mercurial repositories or "forests" which contain the source files and their change history. The promoted builds are performed using the source in the MASTER forest of repositories. Each OpenJDK group may sponsor projects which may have clones of the MASTER repositories, called project repositories. Individual contributors will have clones of the project repositories associated with the code they are modifying.
Repositories may be either read-only or read/write. Clones are made from read-only repositories. Changeset pushes are made into the read/write repositories, which are called gate repositories. After the new changeset(s) are verified they're pushed to the read-only repositories for all to see.
The need for both read-only and read/write repositories is due to the way that repository locking works in Mercurial.
The repositories use following naming scheme:
<release>/<project>{-gate}?/<component>
where
release :: the name of the release such as "jdk7" project :: the name of an OpenJDK project such as "swing", "tl", or "build" component :: the name of a repository containing a logical subset of the code base such as "langtools"
The OpenJDK repository forests are located at http://hg.openjdk.java.net/.
Projects
The following table summarizes the existing set of projects and the mailing lists which may be used to contact the associated development teams.
| Name | Description | Contact Mailing Lists |
|---|---|---|
| 2d | 2D Graphics API and implementation as provided by members of the 2D Graphics group | 2d-dev |
| awt | AWT API and implementation including the event handling system, the "heavyweight" GUI components as provided by members of the AWT group | awt-dev |
| build | Changes sponsored by the build team (also know as Release Engineering or RE) | build-dev |
| corba | CORBA API and implementation supplied by CORBA developers in the GlassFish Corba project | CORBA lists |
| hotspot | Merge forest for all portions of the Hotspot virtual machine | hotspot-dev |
| hotspot-comp | Hotspot Compiler implementation as provided by members of the Hotspot group | hotspot-compiler-dev |
| hotspot-gc | Hotspot Garbage Collection implementations as provided by members of the Hotspot group | hotspot-gc-dev |
| hotspot-rt | Hotspot Runtime and Serviceability implementation as provided by members of the Hotspot and Serviceability groups | hotspot-runtime-dev and serviceability-dev |
| i18n | Internationalization API and implementation as provided by the Intenationalization group | i18n-dev |
| jaxp | JAXP API and implementation supplied by JAXP developers in the GlassFish JAXP project | JAXP lists |
| jaxws | JAX-WS and JAXB API and implementation supplied by developers in the GlassFish JAX-WS and JAXB projects | JAX-WS
lists and JAXB lists |
| l10n | Localization as provided by the Localization portion of the Internationalization group | i18n-dev |
| modules | JSR-277: Java Module System and JSR-294: Improved Modularity Support in the Java Programming Language APIs and implemenations being developed by the Modules project | modules-dev |
| nio2 | JSR-203: More New I/O APIs for the Java Platform ("NIO.2") APIs and implementations being developed by the NIO2 project | TBD |
| swing | Swing API and implementation including windows, buttons, scrollbars, file choosers, color choosers and combo boxes as provided by members of the Swing group | swing-dev |
| tl | Tools and Libraries APIs and implementation as provided by the Core Libraries, Compiler, libraries portions of Serviceability, JMX, Security, and Networking groups. Security includes cryptography, public key infrastructure, secure communication, authentication, and access control. | corelibs-dev, compiler-dev, serviceability-dev, jmx-dev, security-dev, and net-dev |
The organization and names of the projects are strongly influenced by historical considerations. In some cases, they may not be intuitive but these associations are difficult to change.
Components
The following table describes the components (or trees) in each forest of repositories.
| Name | Description |
|---|---|
| corba | CORBA APIs and supporting implementation as supplied by the GlassFish Corba project |
| hotspot | Hotspot virtual machine implementation including serviceability support |
| jaxp | JAXP APIs and supporting implementation as supplied by the GlassFish JAXP project |
| jaxws | JAXB and JAX-WS APIs and supporting implementation as supplied by the GlassFish JAX-WS and JAXB projects |
| langtools | javac, javah, javap, and other language tools and the API and implementation for JSR-199: Java Compiler API |
| jdk | All other parts of the JDK not part of the previous components including core libraries, swing, internationalization, security, rmi, … |
Installing and Configuring Mercurial
Mercurial is a free, cross-platform, distributed source management tool. Source bundles and binary packages for Mercurial are available at http://www.selenic.com/mercurial/wiki/index.cgi.
The OpenJDK repositories require installation of Mercurial 0.9.4 (or later). The script make/scripts/hgforest.sh can help in applying commands to all the repositories in the forest.
Create and edit the ~/.hgrc file to minimally
contain the following entries:
[ui] username = <jdk_username> [extensions] fetch=
jdk_username is a plain lowercase, alphanumeric token (not an e-mail address) with twelve characters or less. The first character should be alphabetic. This username will be publicly visible in all Mercurial changeset logs. It will be used to verify that the changeset author has commit access to the repository. It is recommended that the jdk_username be somehow related to the author's full name, such as the author's initials or the first character of the author's first name followed by the author's last name.
Verifying the Configuration
After installing and configuring Mercurial, validate the configuration using the following steps.
- Verify that Mercurial is version 0.9.4 (or newer).
$ hg version Mercurial Distributed SCM (version 0.9.4) Copyright (C) 2005-2007 Matt Mackall <mpm@selenic.com> and others This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- Verify that the list of available commands is as expected,
including fetch.
$ hg help full output
- Verify that the
~/.hgrcconfiguration looks correct. Minimally it should contain the following entries:$ hg showconfig extensions.fetch= ui.username=iris
At this point, it should be possible to start retrieving source from the repositories.
Cloning
With Mercurial each developer works with a clone of the repository which is a snapshot of the files at the time the clone was taken. To update the clone, see Producing a Changeset.
… a Sandbox Repository
In addition to the project repositories, there are some test repositories that may be used to run test commands against Mercurial without fear of causing damage to production source. Use them freely but with discretion; content in them may be deleted at any time.
$ mkdir sandbox; cd sandbox $ hg clone http://hg.openjdk.java.net/sandbox/box destination directory: box requesting all changes adding changesets adding manifests adding file changes added 23 changesets with 24 changes to 5 files 4 files updated, 0 files merged, 0 files removed, 0 files unresolved $ du -s box 46 box
… a Forest
It is strongly recommended for developers to clone the entire
project's forest, rather than a single repository. This is the only
means to ensure consistency in builds. The follow example
illustrates how to clone the entire tl forest into the
directory mytl.
$ mkdir jdk7; cd jdk7 $ hg clone http://hg.openjdk.java.net/jdk7/tl mytl requesting all changes adding changesets adding manifests adding file changes added 345 changesets with 344 changes to 33 files updating to branch default 32 files updated, 0 files merged, 0 files removed, 0 files unresolved $ cd mytl $ sh ./get_source.sh full output $ du -s 395183 . $ ls mytl ASSEMBLY_EXCEPTION THIRD_PARTY_README jaxws LICENSE corba jdk Makefile get_source.sh langtools README hotspot make README-builds.html jaxp test
… a Single Repository
If reading a limited portion of the source is the only goal, it
is possible to clone a single repository from a project forest. For
instance, this example shows how to clone the
langtools repository from the tl project into
the default destination directory.
$ hg clone http://hg.openjdk.java.net/jdk7/jdk7/tl/langtools destination directory: langtools requesting all changes adding changesets adding manifests adding file changes added 2 changesets with 26 changes to 26 files 26 files updated, 0 files merged, 0 files removed, 0 files unresolved $ du -s langtools 414 langtools
