build.rst (9159B)
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 30 To install prerequisites on different platforms, one can run the following 31 commands: 32 33 **On Linux:** 34 35 .. code:: 36 37 sudo apt install mercurial git ninja-build python3-pip 38 python3 -m pip install gyp-next 39 40 **On MacOS:** 41 42 .. code:: 43 44 brew install mercurial git ninja python3-pip 45 python3 -m pip install gyp-next 46 47 **On Windows:** 48 49 .. code:: 50 51 <TODO> 52 53 .. note:: 54 To retrieve the source code from the project repositories, users will need to 55 download a release or pull the source code with their favourite Version 56 Control System (git or Mercurial). Installing a VCS is not necessary to build 57 an NSS release when downloaded as a compressed archive. 58 59 By default Mozilla uses a Mercurial repository for NSS. If you whish to 60 contribute to NSS and use ``git`` instead of Mercurial, we encourage you to 61 install `git-cinnabar <https://github.com/glandium/git-cinnabar>`__. 62 63 .. 64 `Windows <#windows>`__ 65 ~~~~~~~~~~~~~~~~~~~~~~ 66 67 .. container:: 68 69 NSS compilation on Windows uses the same shared build system as Mozilla 70 Firefox. You must first install the `Windows Prerequisites 71 <https://firefox-source-docs.mozilla.org/setup/windows_build.html>`__, 72 including **MozillaBuild**. 73 74 You can also build NSS on the Windows Subsystem for Linux, but the resulting binaries aren't 75 usable by other Windows applications. 76 77 .. _get_the_source: 78 79 `Source code <#get_the_source>`__ 80 --------------------------------- 81 82 .. container:: 83 84 NSS and NSPR use Mercurial for source control like other Mozilla projects. To 85 check out the latest sources for NSS and NSPR--which may not be part of a 86 stable release--use the following commands: 87 88 .. code:: 89 90 hg clone https://hg.mozilla.org/projects/nspr 91 hg clone https://hg.mozilla.org/projects/nss 92 93 94 **To get the source of a specific release, see:** 95 ref:`mozilla_projects_nss_releases` **.** 96 97 To download the source using ``git-cinnabar`` instead: 98 99 .. code:: 100 101 git clone hg::https://hg.mozilla.org/projects/nspr 102 git clone hg::https://hg.mozilla.org/projects/nss 103 104 105 `Build with gyp and ninja <#build>`__ 106 ------------------------------------- 107 108 .. container:: 109 110 Build NSS and NSPR using our build script from the ``nss`` directory: 111 112 .. code:: 113 114 cd nss 115 ./build.sh 116 117 This builds both NSPR and NSS in a parent directory called ``dist``. 118 119 Build options are available for this script: ``-o`` will build in **Release** 120 mode instead of the **Debug** mode and ``-c`` will **clean** the ``dist`` 121 directory before the build. 122 123 Other build options can be displayed by running ``./build.sh --help`` 124 125 .. _build_with_make: 126 127 `Build with make <#build_with_make>`__ 128 -------------------------------------- 129 130 .. container:: 131 132 Alternatively, there is a ``make`` target, which produces a similar 133 result. This supports some alternative options, but can be a lot slower. 134 135 .. code:: 136 137 USE_64=1 make -j 138 139 The make-based build system for NSS uses a variety of variables to control 140 the build. Below are some of the variables, along with possible values they 141 may be set to. 142 143 .. csv-table:: 144 :header: "BUILD_OPT", "" 145 :widths: 10,50 146 147 "0", "Build a debug (non-optimized) version of NSS. **This is the default.**" 148 "1", "Build an optimized (non-debug) version of NSS." 149 150 .. csv-table:: 151 :header: "USE_64", "" 152 :widths: 10,50 153 154 "0", "Build for a 32-bit environment/ABI. **This is the default.**" 155 "1", "Build for a 64-bit environment/ABI. *This is recommended.*" 156 157 .. csv-table:: 158 :header: "USE_ASAN", "" 159 :widths: 10,50 160 161 "0", "Do not create an `AddressSanitizer 162 <http://clang.llvm.org/docs/AddressSanitizer.html>`__ build. **This is the default.**" 163 "1", "Create an AddressSanitizer build." 164 165 166 .. _unit_testing: 167 168 `Unit testing <#unit_testing>`__ 169 -------------------------------- 170 171 .. container:: 172 173 NSS contains extensive unit tests. Scripts to run these are found in the ``tests`` directory. 174 Run the standard suite by: 175 176 .. code:: 177 178 HOST=localhost DOMSUF=localdomain USE_64=1 ./tests/all.sh 179 180 .. _unit_test_configuration: 181 182 `Unit test configuration <#unit_test_configuration>`__ 183 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 184 185 .. container:: 186 187 NSS tests are configured using environment variables. 188 The scripts will attempt to infer values for ``HOST`` and ``DOMSUF``, but 189 can fail. Replace ``localhost`` and ``localdomain`` with the hostname and 190 domain suffix for your host. You need to be able to connect to 191 ``$HOST.$DOMSUF``. 192 193 If you don't have a domain suffix you can add an entry to ``/etc/hosts`` (on 194 Windows,\ ``c:\Windows\System32\drivers\etc\hosts``) as follows: 195 196 .. code:: 197 198 127.0.0.1 localhost.localdomain 199 200 Validate this opening a command shell and typing: ``ping localhost.localdomain``. 201 202 Remove the ``USE_64=1`` override if using a 32-bit build. 203 204 .. _test_results: 205 206 `Test results <#test_results>`__ 207 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 208 209 .. container:: 210 211 Running all tests can take a considerable amount of time. 212 213 Test output is stored in ``tests_results/security/$HOST.$NUMBER/``. The file 214 ``results.html`` summarizes the results, ``output.log`` captures all the test 215 output. 216 217 Other subdirectories of ``nss/tests`` contain scripts that run a subset of 218 the full suite. Those can be run directly instead of ``all.sh``, which might 219 save some time at the cost of coverage. 220 221 .. _mozilla_projects_nss_build_artifacts: 222 223 `Build artifacts <#build_artifacts>`__ 224 -------------------------------------- 225 226 .. _shared_libraries: 227 228 `Shared libraries <#shared_libraries>`__ 229 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 230 231 .. container:: 232 233 Network Security Services provides both static libraries and shared libraries. Applications that 234 use the shared libraries must use only the APIs that they export. Three shared libraries export 235 public functions: 236 237 - The SSL/TLS library supports core TLS operations. 238 - The S/MIME library supports core S/MIME operations. 239 - The freebl library supports core crypto operations. 240 241 .. note:: 242 243 We guarantee that applications using the exported APIs will remain compatible with future 244 versions of those libraries until deprecated. 245 246 .. _naming_conventions_and_special_libraries: 247 248 `Naming conventions <#naming_conventions_and_special_libraries>`__ 249 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 250 251 .. container:: 252 253 Windows and Unix use different naming conventions for static and dynamic 254 libraries: 255 256 ======= ======== =============================== 257 Windows Unix 258 static ``.lib`` ``.a`` 259 dynamic ``.dll`` ``.so`` or ``.dylib`` or ``.sl`` 260 ======= ======== =============================== 261 262 In addition, Windows has "import" libraries that bind to dynamic 263 libraries. So the NSS library has the following forms: 264 265 - ``libnss3.so`` - Linux shared library 266 - ``libnss3.dylib`` - MacOS shared library 267 - ``libnss3.sl`` - HP-UX shared library 268 - ``libnss.a`` - Unix static library 269 - ``nss3.dll`` - Windows shared library 270 - ``nss3.lib`` - Windows import library binding to ``nss3.dll`` 271 - ``nss.lib`` - Windows static library 272 273 NSS, SSL, and S/MIME have all of the above forms. 274 275 The following static libraries aren't included in any shared libraries 276 277 - ``libcrmf.a``/``crmf.lib`` provides an API for CRMF operations. 278 - ``libjar.a``/``jar.lib`` provides an API for creating JAR files. 279 280 The following static libraries are included only in external loadable PKCS 281 #11 modules: 282 283 - ``libnssckfw.a``/``nssckfw.lib`` provides an API for writing PKCS #11 modules. 284 - ``libswfci.a``/``swfci.lib`` provides support for software FORTEZZA. 285 286 The following shared libraries are standalone loadable modules, not meant to 287 be linked with directly: 288 289 - ``libfort.so``/``libfort.sl``/``fort32.dll`` provides support for hardware FORTEZZA. 290 - ``libswft.so``/``libswft.sl``/``swft32.dll`` provides support for software FORTEZZA. 291 - ``libnssckbi.so``/``libnssckbi.sl``/``nssckbi.dll`` defines the default set 292 of trusted root certificates.