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.
Operations which are performed repeatedly, such as creating changesets, merging, and pushing are described in Producing a Changeset.
The JDK source is available from other locations, for examplesrc.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.
- 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 "modules" 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 implementation as provided by members of the Hotspot group | hotspot-runtime-dev |
| hotspot-svc | Hotspot portion of the Serviceability implementation as provided by members of the Serviceability group | 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 |
| jsn | Security and Networking APIs and implementations as provided by members of the Security and Networking groups respectively. Security includes cryptography, public key infrastructure, secure communication, authentication, and access control. | security-dev and net-dev |
| 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, and JMX groups. This project also serves as the merging area for the jsn project. | corelibs-dev, compiler-dev, serviceability-dev, jmx-dev, and mailing lists associated with the jsn project |
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). It also requires the latest Forest Extension which is not distributed with Mercurial and must be obtained in source form after Mercurial is installed. (Yes, the extension is itself stored in a Mercurial repository.)
Thorough install instructions for Unix are available at
http://www.selenic.com/mercurial/wiki/index.cgi/UnixInstall.After installing Mercurial, acquire and install the Forest Extension available at
http://www.selenic.com/mercurial/wiki/index.cgi/ForestExtension.
Create and edit the ~/.hgrc file to minimally
contain the following entries:
[ui] username = <jdk_username> [extensions] forest= 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 includes those
provided by the Forest Extension (for instance
fcloneandfpull).$ hg help full output
- Verify that the
~/.hgrcconfiguration looks correct. Minimally it should contain the following entries:$ hg showconfig extensions.fetch= extensions.forest= 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 fclone http://hg.openjdk.java.net/jdk7/tl mytl full output $ du -s 395183 . $ ls mytl ASSEMBLY_EXCEPTION README-builds.html jaxp junk.abc LICENSE THIRD_PARTY_README jaxws langtools Makefile corba jdk make README hotspot junk testfile
… 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
