Source code
Revision control
Copy as Markdown
Other Tools
(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++
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
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}
```
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
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.
:::