Repositories

version 0.02
« Previous • TOC • Next »

This section describes the OpenJDK repository terminology and naming scheme. It also includes minimal instructions to acquire source from the OpenJDK repository, http://hg.openjdk.java.net/.

Note that source may be available from other locations, for example src.zip from a full JDK distribution. However, OpenJDK contributions must use source from the OpenJDK Mercurial repository 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.

This document assumes familiarity with the first two chapters of the free on-line book Mercurial: The Definitive Guide.

Terminology and Naming Scheme

The OpenJDK code base for all Projects is stored in Mercurial repositories which contain the source files and their change history. Some Projects may choose to organize their code into multiple, possibly related, Mercurial repositories. For instance, JDK 9 uses a forest of multiple related repositories which contain components of the entire JDK. Projects which are based on the JDK, such as IcedTea and Jigsaw also use this model. In contrast, Code Tools uses an unrelated repository for each tool and Graal uses only a single repository. Regardless of how a Project has chosen to store their code, each Contributor clones the repository associated with the code they are modifying.

Consult the Project's documentation or mailing list to determine the appropriate repository, development conventions, and helpful tools.

This is the typical development model:

Diagram of server repos and user's clone

A Contributor creates a clone (a local copy called "9dev") of a read/write repository ("jdk9/dev") which resides on the OpenJDK Mercurial server. They work on their change in the clone and locally commit a changeset. After the new changeset(s) are verified, they're either pushed directly from the clone or exported and delivered to a Committer who can perform the push into the server repository for all to see.

The use of gate repositories was eliminated when the Mercurial servers were upgraded in March 2014.

The repositories use the following naming scheme:

<project>/<component_path>

where

project :: the short name of an OpenJDK Project such as "jdk9", "openjfx", or "sumatra"
component_path :: the path to a repository containing the code base as designated by the Project Lead.

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 recommend installation of Mercurial 2.6.3 (or later). A Mercurial installation is sufficient to clone a repository. Contributors who wish to submit changes will need some additional configuration as described below.

Some Projects may recommend additional tools or scripts that help with repository manipulation and code development. For instance, in JDK 9, the utility script common/bin/hgforest.sh may be used to apply commands to all the repositories in the forest. Popular extensions for OpenJDK developers include jcheck, trees, and Mercurial Queues (mq). Note that trees is enabled on the OpenJDK Mercurial server.

Create and edit the ~/.hgrc file to minimally contain the following entry:

[ui]
username = <openjdk_username>

openjdk_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 is at least an Author for the Project and that the person pushing the changeset is at least a Committer. It is recommended that the openjdk_username be somehow related to the Author's full name, such as the first character of the Author's first name followed by the Author's last name. Refer to the Becoming an Author section of the Project page for additional information.

An alphabetical list of all of the assigned openjdk_usernames may be found on the OpenJDK people list. The Census shows the structure of the OpenJDK Community.

Verifying the Configuration

After installing and configuring Mercurial, validate the configuration using the following steps.

  1. Verify that Mercurial is version 2.6.3 (or newer). 
    $ hg version
Mercurial Distributed SCM (version 2.9)
(see http://mercurial.selenic.com for more information)

Copyright (C) 2005-2014 Matt Mackall 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.
  2. Verify that the list of enabled extensions includes fetch and mq. 
    $ hg help
full output
  3. Verify that the ~/.hgrc configuration looks correct. Minimally it should contain the following entries: 
    $ hg showconfig
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 development 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

If a Project uses a forest, It is strongly recommended for developers to clone an entire forest, rather than a single repository. This is the only means to ensure consistency in builds. The following examples illustrate two alternatives for cloning the entire jdk9/dev forest into the directory 9dev.

  1. To clone the forest using the trees extension just use tclone:

    $ hg tclone http://hg.openjdk.java.net/jdk9/dev 9dev
full output

  2. To clone the forest using get_source.sh, first clone the main tree:

    $ hg clone http://hg.openjdk.java.net/jdk9/dev 9dev
requesting all changes
adding changesets
adding manifests
adding file changes
added 997 changesets with 1477 changes to 138 files
updating to branch default
82 files updated, 0 files merged, 0 files removed, 0 files unresolved

    Then clone the repositories in the forest:

    $ cd 9dev
$ sh ./get_source.sh
full output

Regardless of how the forest was cloned, this is the resulting populated forest.

$ du -s 
934532  .
$ ls
ASSEMBLY_EXCEPTION  hotspot    LICENSE   README-builds.html
common              jaxp       make      test
configure           jaxws      Makefile  THIRD_PARTY_README
corba               jdk        nashorn
get_source.sh       langtools  README

… a Single Repository

If the source for the Project is contained within a single repository or reading a limited portion of the source is the only goal, it is possible to clone a single repository (even if it's part of a forest). For instance, this example shows how to clone the langtools repository from jdk9/dev into the default destination directory.

$ hg clone http://hg.openjdk.java.net/jdk9/dev/langtools
destination directory: langtools
requesting all changes
adding changesets
adding manifests
adding file changes
added 2289 changesets with 21194 changes to 7004 files
updating to branch default
6212 files updated, 0 files merged, 0 files removed, 0 files unresolved
$ du -s langtools
84396   langtools
version 0.02
« Previous • TOC • Next »