This page is primarily intended for developers of Mercurial.

{i} This page appears to contain material that is no longer relevant. Please help improve this page by updating its content.

Building The Mercurial Book

Information on building Mercurial: The Definitive Guide from source.

1. Mercurial Book Building Environment

1.1. What is MBBE (mercurial book building environment) ?

2. The book building process in ASCII flow chart

2.1. How do I setup MBBS using Fedora VMWare appliance approach ?

  1. Download VMWare player 2.0 or using VMWare workstation/VMWare ESX if you have a license.

  2. Download Fedora 7 vmware image from Though police.

  3. Use YUM install the missing rpm packages.
    • [root@localhost ~]# yum install yum graphviz tetex mercurial rcs inkscape patchutils tex4ht tetex-latex Django

2.2. How do I setup MBBS using OpenSolaris x86/Solaris 10 x86 VMWare appliance approach ?

Followings are just brief steps.

  1. create a vmware session using Solaris 10.
  2. get the book system needed software.

2.3. How do I check in the changes I made ?

  1. TBA.

2.4. How do I back out the changes in Mercurial book changes history ?

  1. Backout to a known working copy to discard the changes.
  2. Ex. the changes set after "271:8627f718517a" break the book building on Fedora 7(also on 6 and 8).
    1. Error message, failed at "run-example bisect".
      cd examples && ./run-example backout
      running backout ..............
      cd examples && ./run-example bisect
      running bisect .....
      Output of has changed!
      ---      2007-12-08 07:47:25.000000000 -0500
      +++      2007-12-08 07:52:01.000000000 -0500
      @@ -1,3 +1 @@
      (exit 0)
      make: *** [examples/] Error 1
      rm undo-non-tip.eps wdir-after-commit.eps wdir-merge.eps undo-manual.eps wdir-br anch.eps metadata.eps snapshot.eps wdir-pre-branch.eps tour-merge-sep-repos.eps  tour-merge-pull.eps revlog.eps tour-merge-conflict.eps tour-merge-merge.eps undo -manual-merge.eps feature-branches.eps undo-simple.eps tour-history.eps filelog. eps wdir.eps mq-stack.eps
      [root@localhost en]#
    2. The change logs
    [root@localhost book]# hg log  | head -40
    changeset:   276:92660e72d6bf
    tag:         tip
    user:        "Dongsheng Song" <>
    date:        Fri Dec 07 21:25:07 2007 -0800
    summary:     [hgbook] Fix a typo
    changeset:   275:96ea24a916f9
    parent:      274:b049cb10bde3
    parent:      273:00f69e8825c5
    user:        Bryan O'Sullivan <>
    date:        Mon Nov 26 20:42:36 2007 -0800
    summary:     Merge with myself.
    changeset:   274:b049cb10bde3
    parent:      271:8627f718517a
    user:        Bryan O'Sullivan <>
    date:        Mon Nov 26 20:42:17 2007 -0800
    summary:     Add a link to myself.
    changeset:   273:00f69e8825c5
    user:        Bryan O'Sullivan <>
    date:        Mon Nov 26 12:24:53 2007 -0800
    summary:     Bring book up to date with recent changes.
    changeset:   272:74c079e0051f
    user:        Bryan O'Sullivan <>
    date:        Mon Nov 26 11:18:46 2007 -0800
    summary:     Account for change in bisect output.
    changeset:   271:8627f718517a
    user:        Max Vozeler <>
    date:        Mon Sep 10 19:38:41 2007 +0200
    summary:     Fix typo "paptches"
    changeset:   270:4c767178c1aa
    user:        Eric Hanchrow <>
    date:        Mon Jun 04 13:23:53 2007 -0700
    summary:     Fix typos
    changeset:   269:abfe426f7e08
    [root@localhost book]#
  3. run the following commands to undo the change after Sept 10 2007. the revision number is 271.
      hg backout --merge -m 'Sep102007' 271

3. Building the book

3.1. Pull hg book source

  1. (mkdir /tmp;cd /tmp )and run following to put source from book source repository

    [root@localhost ~]# hg clone
    destination directory: book
    requesting all changes
    adding changesets
    adding manifests
    adding file changes
    added 277 changesets with 855 changes to 319 files
    315 files updated, 0 files merged, 0 files removed, 0 files unresolved
    [root@localhost ~]#

3.2. Remove existing book/en/examples/*.out file

3.3. Do a dry run to see what is going to happen

3.4. Making the book

3.5. A Complete Successful book build log

4. Error Messages

4.1. "output of bisect.init has changed"

4.2. GDK_IS_DISPLAY (display)' failed

4.3. Recent Success on Ubuntu

I was able to build the PDF version of hgbook on a recent Ubuntu machine. hgbook version 5225ec140003, Ubuntu version 9.04. It required all of the packages in the README.BUILD as well as libxml-commons-resolver1.1-java.

My Makefile.vars has one line: JAVA_LIB=/usr/share/java The Makefile required some tweaking. The classpath on line 225 looks like this:

java -classpath $(JAVA_LIB)/saxon.jar:$(JAVA_LIB)/saxon-jdom.jar:$(JAVA_LIB)/docbook-xsl-saxon.jar:$(JAVA_LIB)/xml-commons-resolver-1.1.jar:$(JAVA_LIB)

And the fop line looks like this

(cd build/$(LINGUA)/source && /usr/bin/fop ../pdf/hgbook.pdf)

I edited stylesheets/fo.xsl to change A4 to letter, but this is not required. I also used the ~/.fonts.conf hack described in the top link on this page. It has a typo (</strong> should be </string>). Not sure if this hack was necessary, but it didn't break anything.

The HTML target works as well, but the text font is not optimal (did not investigate).

I only built the English version.

make LINGUA=en pdf html

CategoryHowTo CategoryDeveloper

BuildingMercurialBook (last edited 2013-09-03 03:31:36 by KevinBot)