.. _mozilla_projects_nss_building: 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._ Two build systems are maintained concurrently: a ``Make`` based and a ``gyp`` based system. .. _build_environment: `Prerequisites <#build_environment>`__ ------------------------------------------ .. container:: NSS needs a C and C++ compiler. It has minimal dependencies, including only standard C and C++ libraries, plus `zlib `__. For building, you also need `make `__. Ideally, also install `gyp-next `__ and `ninja `__ and put them on your path. This is recommended, as the build is faster and more reliable. Please, note that we ``gyp`` is currently unmaintained and that our support for ``gyp-next`` is experimental and might be unstable. To install prerequisites on different platforms, one can run the following commands: **On Linux:** .. code:: sudo apt install mercurial git ninja-build python3-pip python3 -m pip install gyp-next **On MacOS:** .. code:: brew install mercurial git ninja python3-pip python3 -m pip install gyp-next It is also necessary to make sure that a `python` (not just `python3`) executable is in the path. The Homebrew Python installation has the necessary symlink but may require explicit adding to the PATH variable, for example like this: .. code:: export PATH="/opt/homebrew/opt/python/libexec/bin:$PATH" **On Windows:** .. code:: .. note:: To retrieve the source code from the project repositories, users will need to download a release or pull the source code with their favourite Version Control System (git or Mercurial). Installing a VCS is not necessary to build an NSS release when downloaded as a compressed archive. By default Mozilla uses a Mercurial repository for NSS. If you whish to contribute to NSS and use ``git`` instead of Mercurial, we encourage you to install `git-cinnabar `__. .. `Windows <#windows>`__ ~~~~~~~~~~~~~~~~~~~~~~ .. container:: NSS compilation on Windows uses the same shared build system as Mozilla Firefox. You must first install the `Windows Prerequisites `__, 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: `Source code <#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:: hg clone https://hg.mozilla.org/projects/nspr hg clone https://hg.mozilla.org/projects/nss **To get the source of a specific release, see:** ref:`mozilla_projects_nss_releases` **.** To download the source using ``git-cinnabar`` instead: .. code:: git clone hg::https://hg.mozilla.org/projects/nspr git clone hg::https://hg.mozilla.org/projects/nss `Build with gyp and ninja <#build>`__ ------------------------------------- .. container:: Build NSS and NSPR using our build script from the ``nss`` directory: .. code:: cd nss ./build.sh This builds both NSPR and NSS in a parent directory called ``dist``. Build options are available for this script: ``-o`` will build in **Release** mode instead of the **Debug** mode and ``-c`` will **clean** the ``dist`` directory before the build. Other build options can be displayed by running ``./build.sh --help`` .. _build_with_make: `Build with make <#build_with_make>`__ -------------------------------------- .. container:: Alternatively, there is a ``make`` target, which produces a similar result. This supports some alternative options, but can be a lot slower. .. code:: USE_64=1 make -j 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. .. csv-table:: :header: "BUILD_OPT", "" :widths: 10,50 "0", "Build a debug (non-optimized) version of NSS. **This is the default.**" "1", "Build an optimized (non-debug) version of NSS." .. csv-table:: :header: "USE_64", "" :widths: 10,50 "0", "Build for a 32-bit environment/ABI. **This is the default.**" "1", "Build for a 64-bit environment/ABI. *This is recommended.*" .. csv-table:: :header: "USE_ASAN", "" :widths: 10,50 "0", "Do not create an `AddressSanitizer `__ build. **This is the default.**" "1", "Create an AddressSanitizer build." .. _unit_testing: `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 ./tests/all.sh .. _unit_test_configuration: `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 <#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.