(mozilla-projects-nss-building-ported)=

# Building NSS

## [Introduction](#introduction)

:::{container}
This page has detailed information on how to build NSS. Because NSS is a cross-platform library
that builds on many different platforms and has many options, it may be complex to build. Please
read these instructions carefully before attempting to build.
:::

## [Build environment](#build_environment)

:::{container}
NSS needs a C and C++ compiler. It has minimal dependencies, including only standard C and C++
libraries, plus [zlib](https://www.zlib.net/).

For building, you also need [make](https://www.gnu.org/software/make/). Ideally, also install
[gyp](https://gyp.gsrc.io/) and [ninja](https://ninja-build.org/) and put them on your
path. This is recommended, as the build is faster and more reliable.
:::

### [Windows](#windows)

:::{container}
NSS compilation on Windows uses the same shared build system as Mozilla Firefox. You must first
install the [Windows
Prerequisites](https://firefox-source-docs.mozilla.org/setup/windows_build.html),
including **MozillaBuild**.

You can also build NSS on the Windows Subsystem for Linux, but the resulting binaries aren't
usable by other Windows applications.
:::

## [Get the source](#get_the_source)

:::{container}
NSS and NSPR use Mercurial for source control like other Mozilla projects. To check out the
latest sources for NSS and NSPR--which may not be part of a stable release--use the following
commands:

```{code}
git clone https://github.com/mozilla/nspr
hg clone https://hg.mozilla.org/projects/nss
```

To get the source of a specific release, see {ref}`mozilla_projects_nss_nss_releases`.
:::

## [Build](#build)

:::{container}
Build NSS using our build script:

```{code}
nss/build.sh
```

This builds both NSPR and NSS.
:::

## [Build with make](#build_with_make)

:::{container}
Alternatively, there is a `make` target called "nss_build_all", which produces a similar
result. This supports some alternative options, but can be a lot slower.

```{code}
make -C nss nss_build_all USE_64=1
```

The make-based build system for NSS uses a variety of variables to control the build. Below are
some of the variables, along with possible values they may be set to.

BUILD_OPT
: 0

  : Build a debug (non-optimized) version of NSS. *This is the default.*

  1

  : Build an optimized (non-debug) version of NSS.

USE_64
: 0

  : Build for a 32-bit environment/ABI. *This is the default.*

  1

  : Build for a 64-bit environment/ABI. *This is recommended.*

USE_ASAN
: 0

  : Do not create an [AddressSanitizer](http://clang.llvm.org/docs/AddressSanitizer.html)
    build. *This is the default.*

  1

  : Create an AddressSanitizer build.
:::

## [Unit testing](#unit_testing)

:::{container}
NSS contains extensive unit tests. Scripts to run these are found in the `tests` directory.
Run the standard suite by:

```{code}
HOST=localhost DOMSUF=localdomain USE_64=1 nss/tests/all.sh
```

:::

### [Unit test configuration](#unit_test_configuration)

:::{container}
NSS tests are configured using environment variables.

The scripts will attempt to infer values for

`HOST`

 and

`DOMSUF`

, but can fail. Replace

`localhost`

 and

`localdomain`

 with the hostname and domain suffix for your host. You need
to be able to connect to

`$HOST.$DOMSUF`

.

If you don't have a domain suffix you can add an entry to `/etc/hosts` (on
Windows,`c:\Windows\System32\drivers\etc\hosts`) as follows:

```{code}
127.0.0.1 localhost.localdomain
```

Validate this opening a command shell and typing: `ping localhost.localdomain`.

Remove the `USE_64=1` override if using a 32-bit build.
:::

### [Test results](#test_results)

:::{container}
Running all tests can take a considerable amount of time.

Test output is stored in `tests_results/security/$HOST.$NUMBER/`. The file `results.html`
summarizes the results, `output.log` captures all the test output.

Other subdirectories of `nss/tests` contain scripts that run a subset of the full suite. Those
can be run directly instead of `all.sh`, which might save some time at the cost of coverage.
:::