1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
|
.. _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 <https://www.zlib.net/>`__.
For building, you also need `make <https://www.gnu.org/software/make/>`__.
Ideally, also install `gyp-next <https://github.com/nodejs/gyp-next>`__ and `ninja
<https://ninja-build.org/>`__ 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:: notranslate
sudo apt install mercurial git ninja-build python3-pip
python3 -m pip install gyp-next
**On MacOS:**
.. code:: notranslate
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:: notranslate
export PATH="/opt/homebrew/opt/python/libexec/bin:$PATH"
**On Windows:**
.. code:: notranslate
<TODO>
.. 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 <https://github.com/glandium/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
<https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Build_Instructions/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:: notranslate
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:: notranslate
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:: notranslate
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:: notranslate
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
<http://clang.llvm.org/docs/AddressSanitizer.html>`__ 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:: notranslate
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:: notranslate
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.
|
