changeset 29:7c3f96e3b7f0

clarify instructions
author jrose
date Mon, 12 Oct 2009 01:22:34 -0700
parents 5958143570a7
children b3c0a99a49f6
files README.txt
diffstat 1 files changed, 27 insertions(+), 3 deletions(-) [+]
line wrap: on
line diff
--- a/README.txt	Fri Aug 07 18:13:21 2009 -0700
+++ b/README.txt	Mon Oct 12 01:22:34 2009 -0700
@@ -47,9 +47,9 @@
 
 === Patch Guards
 
-The series file contains guard annotations for each patch.  Patches are guarded with Mercurial revision hashes that they are known apply to.  (They may additionally be guarded with OpenJDK release tags or other tags.)  In this way, as the OpenJDK repositories advance, 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.
+The series file contains guard annotations for each patch.  Patches are guarded with Mercurial revision hashes that they are known apply to.  (They may additionally be guarded with OpenJDK release tags or other tags.)  In this way, as the OpenJDK repositories advance, patches can be rebased independently from each other.
 
-Each patch must have one or more positive guards.  At last one guard must be a twelve-digit hexadecimal mercurial revision hash, such as "7836be3e92d0".  If a patch is guarded by such a revision, it is guaranteed to apply, without rejects, to that particular OpenJDK build, and to build successfully.
+Each patch must have one or more positive guards.  At least one guard must be a twelve-digit hexadecimal mercurial revision hash, such as "7836be3e92d0".  If a patch is guarded by such a revision, it is guaranteed to apply, without rejects, to that particular OpenJDK build.  It will also build successfully (unless it is marked non-buildable, via a #-buildable guard).
 
 Other tags may be present, especially tags of OpenJDK builds, such as "jdk7-b25".  As it happens, "7836be3e92d0" and "jdk7-b25" refer to the same revision in the hotspot repository.  These symbolic tags are informational and approximate, and (being less accurate than hashes) do not guarantee clean application of patches.
 
@@ -72,6 +72,8 @@
 
 The first line of each series file must contain a twelve-digit hexadecimal number, which declares the base Mercurial revision for the patch series as a whole.  The script patches/make/current-release.sh will scan this revision automatically.  By convention, the first line of the series file can be a handy human-readable description of that base.  If it were missing, the hexadecimal number would be extracted from the tag on the first patch in the series.
 
+When any patch is rebased, the commit which updates the patch must also update patch's guard in the series file also.  This should be done a special "rebasing patch commit" which is distinct from actual development.  Actual development occur in patch commits that are *not* rebasing.
+
 References:
 * more on guards: http://hgbook.red-bean.com/hgbookch13.html
 * patch rebasing procedures: http://www.selenic.com/mercurial/wiki/index.cgi/MqMerge
@@ -105,7 +107,7 @@
 	$ (cd patches/make; gnumake)
 	$ (cd patches/make; gnumake FORCE_VERSIONS=1) # include the force by default
 
-The "gnumake setup" command is likely to fail, if the source version of each sub-repository is not exactly the same as the version advertised in the first line of its series file.  If it fails, the "force" target cleans up by running "hg update" (a.k.a. "hg checkout") to force the repository back to the required revision.
+The "gnumake setup" command is likely to fail, if the source version of each sub-repository is not exactly the same as the version advertised in the first line of its series file.  If it fails, the "force" target cleans up by running "hg update" (a.k.a. "hg checkout") to force the repository back to the required revision.  See the section above on "Patch Guards" to determine the required base revision.
 
 Instead of using the makefile, the following shell commands will work as well:
 	$ bash patches/make/link-patch-dirs.sh sources patches
@@ -128,3 +130,25 @@
 If you have forced the repository, the last command may produce a warning about "working directory not at tip".  This is normal.  It reminds you that you are working with an older version of the software.
 
 (To apply other sets of patches, adjust the guard settings and/or use qpush to refer to specific desired patches.  Do not make permanent edits to the series file, unless they reflect true changes of development status.)
+
+== Trouble Shooting ==
+
+To verify that the current release is properly checked out, you can use Mercurial commands like these in the source directory:
+	cd davinci/sources/hotspot
+	hg qpop -a  # following commands assume no patches active
+	hg parent  # output should include the 12-digit hash of the working version
+	R_CUR=$(hg parent --template '{node|short}\n')
+	head -1 < .hg/patches/series # header comment describes main base revision
+	R_REQ=$(head -1 < .hg/patches/series | awk '{print $4}')  # should be main base revision
+	[ $R_REQ = $R_CUR ] || echo "*** WRONG PATCH BASE"
+
+The 'checkout' command can be used to reset a clean source repository to the base revision required for patches:
+	hg qpop -a  # following commands assume no patches active
+	hg checkout $R_REQ
+	R_CUR=$(hg parent --template '{node|short}\n')
+	[ $R_REQ = $R_CUR ] || echo "*** CHECKOUT FAILED"
+	hg qselect buildable testable $R_CUR
+	hg qpush -a
+	R_QPAR=$(hg log -r qparent --template '{node|short}\n')
+	[ $R_REQ = $R_QPAR ] || echo "*** QUEUE PUSH FAILED"
+