= Building NSS on Windows =

== Preamble ==

NSS stands for [http://www.mozilla.org/projects/security/pki/nss/ Network Security Services]. NSS is required to use SSL in Pidgin. 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, there's and NSS with NSPR package which is compact thus it contains all sources required to build NSS.

To avoid confusion, building NSS on Windows doesn't make use of Cygwin. If you have it (or an other version of MinGW) installed on your computer, it's a good idea to rename its folder until you're finished building NSS to avoid conflicts.

'''Note''': at the moment you can't build NSS completely using GCC. It fails at the final stage when linking additional tools. However, you can build all the important libraries successfully. It will hopefully be improved in the future.

== Prerequisites ==

 1. Get NSS

  Download [ftp://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_12_5_RTM/src/nss-3.12.5-with-nspr-4.8.2.tar.gz NSS with NSPR 3.12.5]. Extract it to `c:\devel\nss-devel`.

 2. Get !MozillaBuild

  Download [http://ftp.mozilla.org/pub/mozilla.org/mozilla/libraries/win32/MozillaBuildSetup-1.4.exe MozillaBuild 1.4] and install it. Install it to `c:\devel\mozilla-build`.

 3. Get MinGW

  This assumes that you have MinGW working as described in the [wiki:BuildingWinPidgin#Themanualway Pidgin Building Instructions] (in short, you need [https://sourceforge.net/projects/mingw/files/Automated%20MinGW%20Installer/ MinGW] installed with at least gcc).

== Choose build flavour ==

The 3 most important options are:

 * target OS
 * optimization
 * debug RTL

You can toggle them with environmental variables. Here's the matrix:

{{{
#!comment
||||BUILD_OPT=0||BUILD_OPT=0||BUILD_OPT=1||BUILD_OPT=1||
||||USE_DEBUG_RTL=0||USE_DEBUG_RTL=1||USE_DEBUG_RTL=0||USE_DEBUG_RTL=1||
||OS_TARGET=WIN95||WIN954.0_DBG.OBJ||WIN954.0_DBG.OBJD||WIN954.0_OPT.OBJ||N/A||
||OS_TARGET=WINNT||WINNT6.1_DBG.OBJ||WINNT6.1_DBG.OBJD||WINNT6.1_OPT.OBJ||N/A||
}}}

{{{
#!rst

=================  =================  =================  =================  =================
        .                      BUILD_OPT=0                           BUILD_OPT=1
-----------------  ------------------------------------  ------------------------------------
        .          USE_DEBUG_RTL=0    USE_DEBUG_RTL=1    USE_DEBUG_RTL=0    USE_DEBUG_RTL=1
=================  =================  =================  =================  =================
OS_TARGET=WIN95    WIN954.0_DBG.OBJ   WIN954.0_DBG.OBJD  WIN954.0_OPT.OBJ   N/A
OS_TARGET=WINNT    WINNT6.1_DBG.OBJ   WINNT6.1_DBG.OBJD  WINNT6.1_OPT.OBJ   N/A
=================  =================  =================  =================  =================

}}}

The version after WINNT is the version of your current OS (you can check it with the `winver` command). WINNT6.1 assumes you're building on Windows 7.

The default values are 0 for numerical variables and current OS for OS_TARGET. So on Windows 7 with no values set you'll end up building WINNT6.1_DBG.OBJ.

Pick the desired configuration (in other words, cell), and set the environmental variables with `set`. Example:

{{{
set BUILD_OPT=1
set OS_TARGET=WIN95
}}}

'''WARNING''': it seems the builder considers any variable as 1 if it's set. So if you enter

{{{
set BUILD_OPT=0
}}}

you'll get an optimized build although you wanted a debug one. The answer lies in `mozilla\security\coreconf\WIN32.mk`. They check variables with ifdefs, which is just plain wrong (or they should mention it this way in the documentation).

'''Solution''': set a variable only if you want the related build. Here's the table for seeing what you actually have to enter and what you'll get:

||||||USE_DEBUG_RTL=1||BUILD_OPT=1||
||OS_TARGET=WIN95||WIN954.0_DBG.OBJ||WIN954.0_DBG.OBJD||WIN954.0_OPT.OBJ||
||OS_TARGET=WINNT||WINNT6.1_DBG.OBJ||WINNT6.1_DBG.OBJD||WINNT6.1_OPT.OBJ||

OS_TARGET is an exception and isn't affected by this error because it's not numerical, so the script checks for its value instead of its existence. As a sidenote, BUILD_OPT seems to have a higher priority, so if you enter

{{{
set BUILD_OPT=1
set USE_DEBUG_RTL=1
}}}

you'll get an optimized build without linking with the debug RTL. In case you want, for example, a debug build after an optimized, you can unset the variable by setting it without a value, such as:

{{{
set BUILD_OPT=
}}}

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 the Mozilla Developer Central.

== Patch NSS ==

There's an error which prevents NSS from building with GCC. Apply the following patch to `c:\devel\nss-devel\nss-3.12.5-with-nspr-4.8.2\mozilla\security\nss\lib\freebl\config.mk`:

{{{
#!diff
--- config.mk.orig	2009-04-12 00:18:42 +0200
+++ config.mk	2010-02-28 20:19:08 +0100
@@ -85,10 +85,14 @@
 RESNAME = freebl.rc

 ifndef WINCE
+ifndef NS_USE_GCC
 OS_LIBS += shell32.lib
 endif
+endif

 ifdef NS_USE_GCC
+OS_LIBS += -lshell32
+DEFINES += -D_WIN32_IE=0x0400
 EXTRA_SHARED_LIBS += \
        -L$(DIST)/lib \
        -L$(NSSUTIL_LIB_DIR) \
}}}

== Build NSS ==

The easiest way to do this with consistent results is to make a build script (the following is what the binary included with Pidgin is built with):
{{{
#!sh
#!/bin/bash

#The path that we've extracted the nss source tarball into
NSS_SRC_DIR=/c/devel/nss-devel

#Set our Build Arguments:
#Optimized Build
export BUILD_OPT=1
#Target Windows NT Family
export OS_TARGET=WINNT
#Use GCC (as opposed to VC)
export NS_USE_GCC=1

#Set up the build path with MinGW and Moztools
PATH=/c/devel/pidgin-devel/win32-dev/mingw/bin:$PATH
PATH=/c/devel/mozilla-build/moztools/bin:$PATH
PATH=/c/devel/mozilla-build/msys/bin:$PATH
export PATH

pushd $NSS_SRC_DIR/nss-3.12.5-with-nspr-4.8.2/mozilla/security/nss
make nss_build_all
popd

}}}

Save this script as `build.sh`. Launch a command prompt and run:

{{{
c:\devel\mozilla-build\msys\bin\sh build.sh
}}}

The build will likely not complete successfully (it will bail out building `.../cmd/bltest`).  If it gets that far, it has built the various libraries successfully.

The resulting binaries will be placed in `c:\devel\nss-devel\nss-3.12.5-with-nspr-4.8.2\mozilla\dist`. The contents of `private` and `public` are the same across all flavours so they can be distributed separately.