= Building NSS on Windows =

== Preamble ==

[http://www.mozilla.org/projects/security/pki/nss/ Network Security Services] (NSS) is the library Pidgin uses for connecting to SSL-enabled servers. NSS depends on NSPR and a [https://wiki.mozilla.org/NSS_Shared_DB shared database] (SQLite since [http://www.mozilla.org/projects/security/pki/nss/nss-3.12/nss-3.12-release-notes.html NSS 3.12]), but you don't have to worry about these as the downloads from Mozilla contain all sources required to build the libraries.

'''Note:''' at the moment you can't build NSS completely using GCC/MinGW. It fails at the final stage when linking additional tools. However, you can build all the important libraries successfully. The instructions below are for building NSS using the Windows Driver Kit (WDK), which does build completely.

== Prerequisites ==

 1. '''GNU Patch:'''[[BR]]Download [http://gnuwin32.sourceforge.net/packages/patch.htm Patch] from the !GnuWin32 project. Note that Windows thinks that "patch.exe" is a patch for a program and will prompt you to UAC elevate it whenever you use it (see [http://math.nist.gov/oommf/software-patchsets/patch_on_Windows7.html this page]).
 1. '''Windows SDK:'''[[BR]]Download the [https://www.microsoft.com/download/en/details.aspx?id=8279 Windows SDK for Windows 7 SP1] and install it to the default location. If you have Visual Studio 2010 Pro or Ultimate installed, this step can be ignored.[[BR]]''NOTE:'' The build script below is written for Visual Studio 2010 and its included SDK - it might be necessary to tweak the script for any other configuration.
 1. '''Windows Driver Kit (WDK):'''[[BR]]Download the [https://www.microsoft.com/download/en/details.aspx?displaylang=en&id=11800 WDK for Windows 7 SP1] and install it to the default location.
 1. '''Network Security Services (NSS) source :'''[[BR]]Download the latest version of [ftp://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/ NSS with NSPR] (currently 3.15.3) and extract it to `c:\devel\pidgin-devel\win32-dev\nss`.
 1. '''MozillaBuild:'''[[BR]]Download the latest version of [ftp://ftp.mozilla.org/pub/mozilla.org/mozilla/libraries/win32/MozillaBuildSetup-Latest.exe MozillaBuild] and install it to `c:\devel\mozilla-build`.
 1. '''WDK build patch:'''[[BR]]Download the [http://www.hexchat.org/ HexChat project]'s [raw-attachment:nss-wdk.2.patch WDK build patch] to `c:\devel\pidgin-devel\win32-dev\nss\nss-wdk.patch`.
 1. '''WDK build script:'''[[BR]]Download [raw-attachment:build-x86.bat this build script] to `c:\devel\pidgin-devel\win32-dev\nss\build-x86.bat`.

== Prepare the build tree ==

Open a command prompt at your NSS/NSPR directory and run `"%PROGRAMFILES(X86)%\GnuWin32\bin\patch" -p1 --dry-run --binary -i nss-wdk.patch`. If there aren't any problems, re-run the command without the `--dry-run` flag.

Once this is done, open `c:\devel\pidgin-devel\win32-dev\nss\build-x86.bat` in your editor of choice and adjust it so that the WDK binaries, mt.exe from the Windows SDK, and lib.exe from the Visual C++ compiler package are all in the PATH. If you have Visual Studio 2010 installed, it should work without modification as long as the paths are correct.

== Choose build configuration ==

The NSS build configuration is controlled by environment variables. The most important options are:

 * Enable optimizations (`BUILD_OPT`)
 * Use debug runtime library (`USE_DEBUG_RTL`)
 * Enable elliptic curve cryptography (`NSS_ENABLE_ECC`)
 * Disable legacy DBM database (`NSS_DISABLE_DBM`)

The first two options select the build type according to the matrix below:

||               ||=  USE_DEBUG_RTL=0  =||=  USE_DEBUG_RTL=1  =||
||  BUILD_OPT=0  ||  WINNT5.1_DBG.OBJ  ||  WINNT5.1_DBG.OBJD  ||
||  BUILD_OPT=1  ||  WINNT5.1_OPT.OBJ  ||      N/A      ||

The version after WINNT is the target OS version - WINNT5.1 assumes you're building for Windows XP.

The second two options control which features are enabled. Normally, both `NSS_ENABLE_ECC` and `NSS_DISABLE_DBM` should be selected.

When using the build script below, the default build is `WINNT5.1_OPT.OBJ` with ECC enabled and DBM disabled. In order to override these settings, set the corresponding environment variables to 0 or 1 before performing the build. Note that this behavior is different than when using the Mozilla makefiles directly. More info about the build variables can be found on the [https://developer.mozilla.org/en/NSS_reference/Building_and_installing_NSS/Build_instructions build instructions] page of Mozilla Developer Central.

== Do the build ==

Launch a Windows XP build environment window (Start > All Programs > Windows Driver Kits > WDK 7600.16385.1 > Build Environments > Windows XP > x86 Free Build Environment) and navigate to `c:\devel\pidgin-devel\win32-dev\nss`. When you're ready to build, run `build-x86` and wait for the build to complete!

The resulting binaries will be placed in `c:\devel\pidgin-devel\win32-dev\nss\nss-<version>\dist`. The contents of `private` and `public` are the same across all configurations so they can be distributed separately. The following files need to be distributed with Pidgin:

 * `libnspr4.dll`
 * `libplds4.dll`
 * `libplc4.dll`
 * `nssutil3.dll`
 * `freebl3.dll`
 * `sqlite3.dll`
 * `softokn3.dll`
 * `nss3.dll`
 * `ssl3.dll`
 * `softokn3.chk`
 * `freebl3.chk`

Generate the zip file for [wiki:BuildingWinPidgin]:
{{{
cp -R nss-<version>/dist/WINNT5.1_OPT.OBJ/ .../pidgin-devel/win32-dev/nss-<version>-nspr-<nsprversion>/
cp -R nss-<version>/dist/public/nss/* .../pidgin-devel/win32-dev/nss-<version>-nspr-<nsprversion>/include/
cd .../pidgin-devel/win32-dev
tar czf nss-<version>-nspr-<nsprversion>.tar.gz nss-<version>-nspr-<nsprversion>
gpg -ab nss-<version>-nspr-<nsprversion>.tar.gz
gpg --verify nss-<version>-nspr-<nsprversion>.tar.gz.asc
}}}