index.rst (4807B)
1 .. _mozilla_projects_nss_building_ported: 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 cross-platform library 12 that builds on many different platforms and has many options, it may be complex to build. Please 13 read these instructions carefully before attempting to build. 14 15 .. _build_environment: 16 17 `Build environment <#build_environment>`__ 18 ------------------------------------------ 19 20 .. container:: 21 22 NSS needs a C and C++ compiler. It has minimal dependencies, including only standard C and C++ 23 libraries, plus `zlib <https://www.zlib.net/>`__. 24 25 For building, you also need `make <https://www.gnu.org/software/make/>`__. Ideally, also install 26 `gyp <https://gyp.gsrc.io/>`__ and `ninja <https://ninja-build.org/>`__ and put them on your 27 path. This is recommended, as the build is faster and more reliable. 28 29 `Windows <#windows>`__ 30 ~~~~~~~~~~~~~~~~~~~~~~ 31 32 .. container:: 33 34 NSS compilation on Windows uses the same shared build system as Mozilla Firefox. You must first 35 install the `Windows 36 Prerequisites <https://firefox-source-docs.mozilla.org/setup/windows_build.html>`__, 37 including **MozillaBuild**. 38 39 You can also build NSS on the Windows Subsystem for Linux, but the resulting binaries aren't 40 usable by other Windows applications. 41 42 .. _get_the_source: 43 44 `Get the source <#get_the_source>`__ 45 ------------------------------------ 46 47 .. container:: 48 49 NSS and NSPR use Mercurial for source control like other Mozilla projects. To check out the 50 latest sources for NSS and NSPR--which may not be part of a stable release--use the following 51 commands: 52 53 .. code:: 54 55 hg clone https://hg.mozilla.org/projects/nspr 56 hg clone https://hg.mozilla.org/projects/nss 57 58 To get the source of a specific release, see :ref:`mozilla_projects_nss_nss_releases`. 59 60 `Build <#build>`__ 61 ------------------ 62 63 .. container:: 64 65 Build NSS using our build script: 66 67 .. code:: 68 69 nss/build.sh 70 71 This builds both NSPR and NSS. 72 73 .. _build_with_make: 74 75 `Build with make <#build_with_make>`__ 76 -------------------------------------- 77 78 .. container:: 79 80 Alternatively, there is a ``make`` target called "nss_build_all", which produces a similar 81 result. This supports some alternative options, but can be a lot slower. 82 83 .. code:: 84 85 make -C nss nss_build_all USE_64=1 86 87 The make-based build system for NSS uses a variety of variables to control the build. Below are 88 some of the variables, along with possible values they may be set to. 89 90 BUILD_OPT 91 0 92 Build a debug (non-optimized) version of NSS. *This is the default.* 93 1 94 Build an optimized (non-debug) version of NSS. 95 96 USE_64 97 0 98 Build for a 32-bit environment/ABI. *This is the default.* 99 1 100 Build for a 64-bit environment/ABI. *This is recommended.* 101 102 USE_ASAN 103 0 104 Do not create an `AddressSanitizer <http://clang.llvm.org/docs/AddressSanitizer.html>`__ 105 build. *This is the default.* 106 1 107 Create an AddressSanitizer build. 108 109 .. _unit_testing: 110 111 `Unit testing <#unit_testing>`__ 112 -------------------------------- 113 114 .. container:: 115 116 NSS contains extensive unit tests. Scripts to run these are found in the ``tests`` directory. 117 Run the standard suite by: 118 119 .. code:: 120 121 HOST=localhost DOMSUF=localdomain USE_64=1 nss/tests/all.sh 122 123 .. _unit_test_configuration: 124 125 `Unit test configuration <#unit_test_configuration>`__ 126 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 127 128 .. container:: 129 130 | NSS tests are configured using environment variables. 131 | The scripts will attempt to infer values for ``HOST`` and ``DOMSUF``, but can fail. Replace 132 ``localhost`` and ``localdomain`` with the hostname and domain suffix for your host. You need 133 to be able to connect to ``$HOST.$DOMSUF``. 134 135 If you don't have a domain suffix you can add an entry to ``/etc/hosts`` (on 136 Windows,\ ``c:\Windows\System32\drivers\etc\hosts``) as follows: 137 138 .. code:: 139 140 127.0.0.1 localhost.localdomain 141 142 Validate this opening a command shell and typing: ``ping localhost.localdomain``. 143 144 Remove the ``USE_64=1`` override if using a 32-bit build. 145 146 .. _test_results: 147 148 `Test results <#test_results>`__ 149 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 150 151 .. container:: 152 153 Running all tests can take a considerable amount of time. 154 155 Test output is stored in ``tests_results/security/$HOST.$NUMBER/``. The file ``results.html`` 156 summarizes the results, ``output.log`` captures all the test output. 157 158 Other subdirectories of ``nss/tests`` contain scripts that run a subset of the full suite. Those 159 can be run directly instead of ``all.sh``, which might save some time at the cost of coverage.