NSS:NewHGLayout

Hints around building, testing and using the new NSS code layout, which involves separate HG (Mercurial) repositories for NSPR and NSS.

One-time preparation

Create a file in your home directory, named .hgrc with the follwing contents, in order to set your preferred 3-way merge tool, your name and email, your preferred diff options, the style of diff/patch output, tell the log command to follow moves, and to enable to mq and rebase extensions:

[ui]
merge = kdiff3
username = YOURNAME <YOUREMAIL>
[defaults]
diff=-U 8 -p
qdiff=-U 8
log = -f 
[diff]
git = 1
nodates = 1
showfunc=true
[merge-tools]
kdiff3.args = $base $local $other -o $output
[extensions]
hgext.mq =
rebase =

Checkout

Prepare a new directory, which will be the common parent directory for multiple trees. Then use multiple commands for the initial checkout code.

mkdir workarea
cd workarea
hg clone https://hg.mozilla.org/projects/nspr
hg clone https://hg.mozilla.org/projects/nss

# optional: get jss
hg clone https://hg.mozilla.org/projects/jss

Building

In order to build both NSPR and NSS in one step, set the usual environment variables, e.g. BUILD_OPT to empty or 1, USE_64 to empty or 1, OS_TARGET to empty or WIN95, etc. (If you're building JSS (java) also set JAVA_HOME.)

Run:

cd workarea/nss
make nss_build_all

# optional: jss
cd workarea/jss
make

Output files

During build, the object files created by the compiler will be created inside the nspr and nss directories. (We use a .hgignore file in each repository to tell hg to ignore them, so that hg commands like "hg stat" will not show them.)

The distribution files and the tests_results files will be created one level above the nspr/nss repositories, inside the workarea:

ls workarea/dist
ls workarea/tests_results

(At a later time, we could change the buildsystem to create all output files outside of the nspr/nss directories, too. However, given that we can use .hgignore, that's not a high priority.)

Testing

Ensure you still have the environment variables used during the build. If necessary, set the HOST and DOMSUF variables and run:

cd workarea/nss/tests
./all.sh

# optional: jss
cd workarea/jss
export PLATFORM=`make platform`
export DISTDIR=`pwd`/../dist
cd org/mozilla/jss/tests
perl all.pl dist $DISTDIR/$PLATFORM

Updating

In order to retrieve new updates from the central HG repository, you can use

hg pull -u

in each of the subdirectories that you have cloned. However, for two reasons it's helpful to use a small script that can be placed into your workarea directory:

• it's inconvenient running the command multiple times in each subdirectory
• it's likely that you'll sooner or later appreciate the MQ extension, which enables you to work with queues of patches.

You could create a file workarea/fetch.sh with the following contents:

cd nspr
QAP=`hg qapplied | wc -l`
if [ "$QAP" -ne "0" ] ; then
  echo "You have mq patches applied! Better qpop them before fetching, to avoid chaos!!! Exiting."
  exit 0
fi
cd ..

cd nss
QAP=`hg qapplied | wc -l`
if [ "$QAP" -ne "0" ] ; then
  echo "You have mq patches applied! Better qpop them before fetching, to avoid chaos!!! Exiting."
  exit 0
fi
cd ..

# remove if you don't use jss
cd jss
QAP=`hg qapplied | wc -l`
if [ "$QAP" -ne "0" ] ; then
  echo "You have mq patches applied! Better qpop them before fetching, to avoid chaos!!! Exiting."
  exit 0
fi
cd ..

echo "no mq patches applied, proceeding..."

cd nspr
hg pull -u -v | tee ../pull-nspr.log
cd ..

cd nss
hg pull -u -v | tee ../pull-nss.log
cd ..

# remove if you don't use jss
cd jss
hg pull -u -v | tee ../pull-jss.log
cd ..

Commit/Push

Before you can push your commits back to the central repository, you must manually configure (once) the .hg/hgrc file inside each repository. While you have cloned using https, and you will pull updates using https, you will push using ssh.

Remember to replace your.email@address.domain with the email address that is used for your account at hg.mozilla.org

nspr/.hg/hgrc:

[paths]
default = https://hg.mozilla.org/projects/nspr/
default-push = ssh://your.email@address.domain@hg.mozilla.org/projects/nspr/

nss/.hg/hgrc:

[paths]
default = https://hg.mozilla.org/projects/nss/
default-push = ssh://your.email@address.domain@hg.mozilla.org/projects/nss/

jss/.hg/hgrc:

[paths]
default = https://hg.mozilla.org/projects/jss/
default-push = ssh://your.email@address.domain@hg.mozilla.org/projects/jss/

Playground

If you'd like to use a playground for experimental and learning purposes:

mkdir playground
cd playground
hg clone http://nss-crypto.org/hg/nspr-playground/ nspr
hg clone http://nss-crypto.org/hg/nss-playground/ nss

Contact kaie if you would like write access.

.hgignore

If not yet present, create a file named .hgignore inside each repository, with the following contents:

syntax: glob
*~
*OPT.OBJ/*
*DBG.OBJ/*
*DBG.OBJD/*

See also

• If you are used to CVS and are learning HG see: NSS:UsingHG
• Mozilla specific FAQs: https://developer.mozilla.org/en-US/docs/Mercurial_FAQ
• General information about HG: http://mercurial.selenic.com/wiki/CvsConcepts