--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/README.txt Tue Apr 15 01:13:41 2008 -0700
@@ -0,0 +1,97 @@
+OpenJDK Multi-Language VM: The Da Vinci Machine Project
+
+This is a Mercurial patch repository.
+
+ See http://openjdk.java.net/ for more information about the OpenJDK.
+
+ See http://openjdk.java.net/projects/mlvm/ for more information
+ about the Da Vinci Machine Project.
+
+
+== Organization
+
+The OpenJDK mlvm/mlvm repository forest is (at present) only a set of patches, not a full set of JDK sources. The patches apply to some version of the full jdk7/jdk7 forest structure. The structure of the mlvm forest parallels the structure of the full jdk7 sources, but each repository in mvlm is only the .hg/patches directory (of the Mercurial mq extension). Thus, repositories under mlvm are called "patch repositories" and those under jdk7 are by contrast called "source repositories".
+
+Commits in the mlvm repositories do not update the full source trees, only the patches. To make this clear, when a commit occurs in a patch repository, we will refer to it specifically as a "patch commit".
+
+=== Patches
+
+All patch files must end with the suffix ".patch".
+
+Patches must not have patch headers, since they are easy to lose if patches are regenerated.
+
+All patches must be in "git" format, without file dates. To ensure this, add the following lines to your ".hgrc" file:
+ [diff]
+ nodates=1
+ git=1
+
+A patch file may be accompanied by a similar file with the suffix ".txt". This file will contain brief comments about the patch, including:
+* references to project documentation, if needed
+* draft commit comments
+* dependencies on other patches
+
+Patch repositories may also contain scripts and documentation. All these non-patch files are ignored by the Mercurial patch queue, since they do not appear in the series file.
+
+Patches may be split. Files that contribute to a split patch must all have the same prefix up to the first dot.
+
+Patches may depend on each other. (For example, invoke dynamic may depend on method handles, which in turn may depend on anonymous classes.) Such dependencies should be clearly stated.
+
+The patch sequence is ordered by both stability and by dependency. If patch B is less stable than patch A, then B should come later in the series. If B depends on A, it also must come later in the series, and A must not be less stable than B.
+
+Patches of the same name in multiple patch repositories (hotspot and jdk) are to be applied simultaneously to parallel source repositories. Their series file elements must be kept exactly in sync. The documenting text file for a patch does not need to be on both sides, and should not be duplicated.
+
+=== Patch Guards
+
+The series file contains guard annotations for each patch. Patches are guarded with the OpenJDK release tags that they apply to. In this way, as the OpenJDK release advances, patches can be rebased independently from each other. Patches must be rebased in a special-purpose "rebasing patch commit" which includes a change to the patch guard in the series file also. Actual development must be placed in patch commits that are *not* rebasing.
+
+Each patch must have one or more positive guards, and each must be the tag of an OpenJDK build, such as "jdk7-b25". If a patch is guarded by such a tag, it is guaranteed to apply, without rejects, to that particular OpenJDK build, and to build successfully.
+
+Each patch must have a negative guard which names that patch with a "slash" prefix. This allows developers to control individual entries in the patch queue without editing the series file. Editing the series file is risky, since it is under version control and shared by all developers. By contrast, the guards file is not under version control.
+
+The following guards are also significant as negative guards on patches which do not yet have the relevant quality level:
+* #-buildable: the patch does not build, or iterferes with the operation of the JVM
+* #-testable: the patch fails to have a working test suite
+
+For normal development, the guards 'buildable' and 'testable' should be present in the guard file, as well as the OpenJDK release in use.
+
+Example series file entries:
+ anonk.patch #-/anonk #+jdk7-b25
+ meth.patch #-/meth #+jdk7-b25
+
+The 'qselect' command can be used to control these patches:
+ hg qselect jdk7-b25 # select both patches, plus any other jdk7-b25 ones
+ hg qselect jdk7-b25 /meth # select anonk but not meth
+
+References:
+* more on guards: http://hgbook.red-bean.com/hgbookch13.html
+* patch rebasing procedures: http://www.selenic.com/mercurial/wiki/index.cgi/MqMerge
+* a good summary on rebasing: http://www.selenic.com/pipermail/mercurial/2008-February/017367.html
+
+=== Multi-based Patches
+
+If a patch must be split so as to apply to several OpenJDK builds, the latest patch in the series must be a complete patch for the most recent build, and for each previous build, a temporary patches must simply track the relevant changes up to the most recent build, so as to make the newest patch apply correctly in all cases.
+
+For example, to support builds 25 and 28 behind build 30 two fixup patches are needed:
+ anonk.jdk7-b25-b30.patch #-/anonk #+jdk7-b25
+ anonk.jdk7-b28-b30.patch #-/anonk #+jdk7-b28
+ anonk.patch #-/anonk #+jdk7-b30 #+jdk7-b28 #+jdk7-b25
+
+Normally this will not be necessary, unless the patch provides functionality which several other patches depend on, and those patches are in different stages of rebasing.
+
+== Setting Up Your Workspace
+
+Make a directory which will contain both sets of repositories (patches and full sources), and pull everything there. Then create symbolic links to the patch directories from the corresponding ".hg" directories of the full sources.
+
+ $ mkdir davinci
+ $ cd davinci
+ $ hg fclone http://hg.openjdk.java.net/jdk7/jdk7 sources
+ $ hg fclone http://hg.openjdk.java.net/mlvm/mlvm patches
+ $ sh patches/make/link-patch-dirs.sh sources patches
+ + ln -s ../../../patches/hotspot sources/hotspot/.hg/patches
+ + ln -s ../../../patches/jdk sources/jdk/.hg/patches
+ $ ls -il patches/hotspot/series sources/hotspot/.hg/patches/series
+ (should be identical files)
+ $ guards="buildable testable $(sh patches/make/current-release.sh)"
+ $ sh patches/make/each-patch-repo.sh hg qselect --reapply $guards
+
+TO DO: Put the details in patches/Makefilem, with a simple build target.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/make/current-release.sh Tue Apr 15 01:13:41 2008 -0700
@@ -0,0 +1,36 @@
+#! /bin/sh
+#
+# Copyright 2008 Sun Microsystems, Inc. All Rights Reserved.
+# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+#
+# This code is free software; you can redistribute it and/or modify it
+# under the terms of the GNU General Public License version 2 only, as
+# published by the Free Software Foundation. Sun designates this
+# particular file as subject to the "Classpath" exception as provided
+# by Sun in the LICENSE file that accompanied this code.
+#
+# This code is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+# version 2 for more details (a copy is included in the LICENSE file that
+# accompanied this code).
+#
+# You should have received a copy of the GNU General Public License version
+# 2 along with this work; if not, write to the Free Software Foundation,
+# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+#
+# Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
+# CA 95054 USA or visit www.sun.com if you need additional information or
+# have any questions.
+
+# Report the last tag in sources/.hgtags.
+# Hopefully, that will be the most recent one also.
+
+sources=${1-sources}
+
+sed -n < "$sources/.hgtags" '
+ s/#.*//; s/^ *//; s/ *$//
+ s/.* //p
+' \
+ |
+tail -1
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/make/each-patch-repo.sh Tue Apr 15 01:13:41 2008 -0700
@@ -0,0 +1,37 @@
+#! /bin/sh
+#
+# Copyright 2008 Sun Microsystems, Inc. All Rights Reserved.
+# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+#
+# This code is free software; you can redistribute it and/or modify it
+# under the terms of the GNU General Public License version 2 only, as
+# published by the Free Software Foundation. Sun designates this
+# particular file as subject to the "Classpath" exception as provided
+# by Sun in the LICENSE file that accompanied this code.
+#
+# This code is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+# version 2 for more details (a copy is included in the LICENSE file that
+# accompanied this code).
+#
+# You should have received a copy of the GNU General Public License version
+# 2 along with this work; if not, write to the Free Software Foundation,
+# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+#
+# Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
+# CA 95054 USA or visit www.sun.com if you need additional information or
+# have any questions.
+
+sources=sources
+
+for d in $(cd "$sources"; echo *); do
+ srepo=$sources/$d
+ # Do not mention a repo if there is no 'series' file.
+ [ ! -f "$srepo/.hg/patches/series" ] && continue
+ case $# in
+ 0) echo "$srepo"; continue;;
+ esac
+ >&2 echo "+ (cd $srepo; $@)"
+ (cd "$srepo"; "$@")
+done
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/make/link-patch-dirs.sh Tue Apr 15 01:13:41 2008 -0700
@@ -0,0 +1,76 @@
+#! /bin/sh
+#
+# Copyright 2008 Sun Microsystems, Inc. All Rights Reserved.
+# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+#
+# This code is free software; you can redistribute it and/or modify it
+# under the terms of the GNU General Public License version 2 only, as
+# published by the Free Software Foundation. Sun designates this
+# particular file as subject to the "Classpath" exception as provided
+# by Sun in the LICENSE file that accompanied this code.
+#
+# This code is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+# version 2 for more details (a copy is included in the LICENSE file that
+# accompanied this code).
+#
+# You should have received a copy of the GNU General Public License version
+# 2 along with this work; if not, write to the Free Software Foundation,
+# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+#
+# Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
+# CA 95054 USA or visit www.sun.com if you need additional information or
+# have any questions.
+
+sources=${1-sources}
+patches=${2-patches}
+case $# in
+[012]) true;;
+*) sources=/no/such/dir;;
+esac
+
+[ ! -d "$sources" -o ! -d "$patches" ] && {
+ >&2 echo "Usage: $0 sources patches"
+ exit 2
+}
+
+shopt -s extglob
+
+here=$(pwd -P)
+sources=$(cd "$sources"; pwd -P)
+patches=$(cd "$patches"; pwd -P)
+
+find "$patches" -name .hg \
+ |
+while read prepo; do
+ prepo=${prepo%"/.hg"}
+ # Do not link a repo if there is no 'series' file.
+ [ ! -f "$prepo/series" ] && continue
+ srepo=$sources/${prepo#"$patches/"}
+ [ ! -d "$srepo/.hg" ] && {
+ >&2 echo "*** Skipping: ${prepo#$here/}"
+ continue
+ }
+ [ -h "$srepo/.hg/patches" ] && {
+ # silently remove previous sym-links
+ rm -f "$srepo/.hg/patches"
+ }
+ [ -r "$srepo/.hg/patches" ] && {
+ >&2 echo "*** Already exists; please remove: ${srepo#$here/}/.hg/patches"; exit 2
+ }
+ linkname="$prepo"
+ [[ "$prepo" == "$here/"* && "$srepo" == "$here"/* ]] && {
+ stepup=${srepo#"$here/"}/.hg
+ stepup=${stepup//+([^\/])/'..'} # turn all path components to '..'
+ linkname=$stepup/${linkname#"$here/"}
+ ( cd "$srepo/.hg"; [ -d "$linkname/." ] ||
+ echo "*** Problem linking: $linkname" )
+ }
+ linkdest=$srepo/.hg
+ linkdest=${linkdest#"$here/"}
+ [ -d "$linkdest" ] || >&2 echo "*** Problem naming: $linkdest"
+ echo + \
+ ln -s "$linkname" "$linkdest/patches"
+ ln -s "$linkname" "$linkdest/patches"
+done