Repositories
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.zipfrom 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.
- Terminology and Naming Scheme defines the nomenclature used by OpenJDK.
- 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 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:
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 Winter 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
and
Mercurial Queues (mq).
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.
- 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 enabled extensions includes fetch and
mq.
$ hg help full output
- Verify that the
~/.hgrcconfiguration 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 follow example illustrates how to clone the entire
jdk9/dev forest into the directory 9dev.
To clone the forest …
$ hg clone http://hg.openjdk.java.net/jdk9/dev 9dev requesting all changes adding changesets adding manifests adding file changes added 965 changesets with 1397 changes to 137 files updating to branch default 81 files updated, 0 files merged, 0 files removed, 0 files unresolved
To clone the repositories in the forest …
$ cd 9dev $ sh ./get_source.sh full output
To view the 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
