security/nss/doc/rst/build.rst

   1 .. _mozilla_projects_nss_building:
   2
   3 Building NSS
   4 ============
   5
   6 `Introduction <#introduction>`__
   7 --------------------------------
   8
   9 .. container::
  10
  11    This page has detailed information on how to build NSS. Because NSS is a
  12    cross-platform library that builds on many different platforms and has many
  13    options, it may be complex to build._ Two build systems are maintained
  14    concurrently: a ``Make`` based and a ``gyp`` based system.
  15
  16 .. _build_environment:
  17
  18 `Prerequisites <#build_environment>`__
  19 ------------------------------------------
  20
  21 .. container::
  22
  23    NSS needs a C and C++ compiler.  It has minimal dependencies, including only
  24    standard C and C++ libraries, plus `zlib <https://www.zlib.net/>`__.
  25    For building, you also need `make <https://www.gnu.org/software/make/>`__.
  26    Ideally, also install `gyp-next <https://github.com/nodejs/gyp-next>`__ and `ninja
  27    <https://ninja-build.org/>`__ and put them on your path. This is
  28    recommended, as the build is faster and more reliable.
  29    Please, note that we ``gyp`` is currently unmaintained and that our support for
  30    ``gyp-next`` is experimental and might be unstable.
  31
  32    To install prerequisites on different platforms, one can run the following
  33    commands:
  34
  35    **On Linux:**
  36
  37    .. code::
  38
  39       sudo apt install mercurial git ninja-build python3-pip
  40       python3 -m pip install gyp-next
  41
  42    **On MacOS:**
  43
  44    .. code::
  45
  46       brew install mercurial git ninja python3-pip
  47       python3 -m pip install gyp-next
  48
  49    It is also necessary to make sure that a `python` (not just `python3`)
  50    executable is in the path.
  51    The Homebrew Python installation has the necessary symlink but may require
  52    explicit adding to the PATH variable, for example like this:
  53
  54    .. code::
  55
  56       export PATH="/opt/homebrew/opt/python/libexec/bin:$PATH"
  57
  58    **On Windows:**
  59
  60    .. code::
  61
  62       <TODO>
  63
  64 .. note::
  65    To retrieve the source code from the project repositories, users will need to
  66    download a release or pull the source code with their favourite Version
  67    Control System (git or Mercurial). Installing a VCS is not necessary to build
  68    an NSS release when downloaded as a compressed archive.
  69
  70    By default Mozilla uses a Mercurial repository for NSS. If you whish to
  71    contribute to NSS and use ``git`` instead of Mercurial, we encourage you to
  72    install `git-cinnabar <https://github.com/glandium/git-cinnabar>`__.
  73
  74 ..
  75    `Windows <#windows>`__
  76    ~~~~~~~~~~~~~~~~~~~~~~
  77
  78    .. container::
  79
  80       NSS compilation on Windows uses the same shared build system as Mozilla
  81       Firefox. You must first install the `Windows Prerequisites
  82       <https://firefox-source-docs.mozilla.org/setup/windows_build.html>`__,
  83       including **MozillaBuild**.
  84
  85       You can also build NSS on the Windows Subsystem for Linux, but the resulting binaries aren't
  86       usable by other Windows applications.
  87
  88 .. _get_the_source:
  89
  90 `Source code <#get_the_source>`__
  91 ---------------------------------
  92
  93 .. container::
  94
  95    NSS and NSPR use Mercurial for source control like other Mozilla projects. To
  96    check out the latest sources for NSS and NSPR--which may not be part of a
  97    stable release--use the following commands:
  98
  99    .. code::
 100
 101       hg clone https://hg.mozilla.org/projects/nspr
 102       hg clone https://hg.mozilla.org/projects/nss
 103
 104
 105    **To get the source of a specific release, see:**
 106    ref:`mozilla_projects_nss_releases` **.**
 107
 108    To download the source using ``git-cinnabar`` instead:
 109
 110    .. code::
 111
 112       git clone hg::https://hg.mozilla.org/projects/nspr
 113       git clone hg::https://hg.mozilla.org/projects/nss
 114
 115
 116 `Build with gyp and ninja <#build>`__
 117 -------------------------------------
 118
 119 .. container::
 120
 121    Build NSS and NSPR using our build script from the ``nss`` directory:
 122
 123    .. code::
 124
 125       cd nss
 126       ./build.sh
 127
 128    This builds both NSPR and NSS in a parent directory called ``dist``.
 129
 130    Build options are available for this script: ``-o`` will build in **Release**
 131    mode instead of the **Debug** mode and ``-c`` will **clean** the ``dist``
 132    directory before the build.
 133
 134    Other build options can be displayed by running ``./build.sh --help``
 135
 136 .. _build_with_make:
 137
 138 `Build with make <#build_with_make>`__
 139 --------------------------------------
 140
 141 .. container::
 142
 143    Alternatively, there is a ``make`` target, which produces a similar
 144    result. This supports some alternative options, but can be a lot slower.
 145
 146    .. code::
 147
 148       USE_64=1 make -j
 149
 150    The make-based build system for NSS uses a variety of variables to control
 151    the build. Below are some of the variables, along with possible values they
 152    may be set to.
 153
 154 .. csv-table::
 155    :header: "BUILD_OPT", ""
 156    :widths: 10,50
 157
 158    "0", "Build a debug (non-optimized) version of NSS. **This is the default.**"
 159    "1", "Build an optimized (non-debug) version of NSS."
 160
 161 .. csv-table::
 162    :header: "USE_64", ""
 163    :widths: 10,50
 164
 165    "0", "Build for a 32-bit environment/ABI. **This is the default.**"
 166    "1", "Build for a 64-bit environment/ABI. *This is recommended.*"
 167
 168 .. csv-table::
 169    :header: "USE_ASAN", ""
 170    :widths: 10,50
 171
 172    "0", "Do not create an `AddressSanitizer
 173    <http://clang.llvm.org/docs/AddressSanitizer.html>`__ build. **This is the default.**"
 174    "1", "Create an AddressSanitizer build."
 175
 176
 177 .. _unit_testing:
 178
 179 `Unit testing <#unit_testing>`__
 180 --------------------------------
 181
 182 .. container::
 183
 184    NSS contains extensive unit tests.  Scripts to run these are found in the ``tests`` directory.
 185    Run the standard suite by:
 186
 187    .. code::
 188
 189       HOST=localhost DOMSUF=localdomain USE_64=1 ./tests/all.sh
 190
 191 .. _unit_test_configuration:
 192
 193 `Unit test configuration <#unit_test_configuration>`__
 194 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 195
 196 .. container::
 197
 198    NSS tests are configured using environment variables.
 199    The scripts will attempt to infer values for ``HOST`` and ``DOMSUF``, but
 200    can fail. Replace ``localhost`` and ``localdomain`` with the hostname and
 201    domain suffix for your host. You need to be able to connect to
 202    ``$HOST.$DOMSUF``.
 203
 204    If you don't have a domain suffix you can add an entry to ``/etc/hosts`` (on
 205    Windows,\ ``c:\Windows\System32\drivers\etc\hosts``) as follows:
 206
 207    .. code::
 208
 209       127.0.0.1 localhost.localdomain
 210
 211    Validate this opening a command shell and typing: ``ping localhost.localdomain``.
 212
 213    Remove the ``USE_64=1`` override if using a 32-bit build.
 214
 215 .. _test_results:
 216
 217 `Test results <#test_results>`__
 218 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 219
 220 .. container::
 221
 222    Running all tests can take a considerable amount of time.
 223
 224    Test output is stored in ``tests_results/security/$HOST.$NUMBER/``.  The file
 225    ``results.html`` summarizes the results, ``output.log`` captures all the test
 226    output.
 227
 228    Other subdirectories of ``nss/tests`` contain scripts that run a subset of
 229    the full suite. Those can be run directly instead of ``all.sh``, which might
 230    save some time at the cost of coverage.