NSS:NewHGLayout

From MozillaWiki
Jump to navigation Jump to search

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