index.rst (6819B)
1 .. _mozilla_projects_nss_nss_sources_building_testing: 2 3 NSS sources building testing 4 ============================ 5 6 .. container:: 7 8 Getting the source code of :ref:`mozilla_projects_nss`, how to build it, and how to run its test 9 suite. 10 11 .. _getting_source_code_and_a_quick_overview: 12 13 `Getting source code, and a quick overview <#getting_source_code_and_a_quick_overview>`__ 14 ----------------------------------------------------------------------------------------- 15 16 .. container:: 17 18 The easiest way is to download archives of NSS releases from `Mozilla's download 19 server <https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/>`__. Find the directory 20 that contains the highest version number. Because NSS depends on the base library 21 `NSPR <https://developer.mozilla.org/en-US/docs/NSPR>`__, you should download the archive that 22 combines both NSS and NSPR. 23 24 If you are a software developer and intend to contribute enhancements to NSS, you should obtain 25 the latest development snapshot of NSS using mercurial/hg (a `distributed source control 26 management tool <https://www.mercurial-scm.org/>`__). In order to get started, anonymous 27 read-only access is sufficient. Create a new directory on your computer that you will use as your 28 local work area, and run the following commands. 29 30 .. code:: sh 31 32 hg clone https://hg.mozilla.org/projects/nspr 33 hg clone https://hg.mozilla.org/projects/nss 34 35 After the above commands complete, you should have two local directories, named nspr and nss, 36 next to each other. 37 38 (Historical information: NSPR and NSS source code have recently been re-organized into a new 39 directory structure. In past versions, all files were located in a directory hierarchy that 40 started with the "mozilla" prefix. The NSPR base library was located in directory 41 mozilla/nsprpub. The subdirectories dbm, security/dbm, security/coreconf, security/nss were part 42 of the NSS sources.) 43 44 The nss directory contains the following important subdirectories: 45 46 - nss/coreconf 47 Contains knowledge for cross platform building. 48 - nss/lib 49 Contains all the library code that is used to create the runtime libraries used by 50 applications. 51 - nss/cmd 52 Contains a set of various tool programs that are built using NSS. Several tools are general 53 purpose and can be used to inspect and manipulate the storage files that software using the 54 NSS library creates and modifies. Other tools are only used for testing purposes. However, all 55 these tools are good examples of how to write software that makes use of the NSS library. 56 - nss/test 57 This directory contains the NSS test suite, which is routinely used to ensure that changes to 58 NSS don't introduce regressions. 59 - nss/gtests 60 Code for NSS unit tests running in `Googletest <https://github.com/abseil/googletest>`__. 61 62 It is important to mention the difference between internal NSS code and exported interfaces. 63 Software that would like to use the NSS library must use only the exported interfaces. These can 64 be found by looking at the files with the .def file extension, inside the nss/lib directory 65 hierarchy. Any C function that isn't contained in .def files is strictly for private use within 66 NSS, and applications and test tools are not allowed to call them. For any functions that are 67 listed in the .def files, NSS promises that the binary function interface (ABI) will remain 68 stable. 69 70 .. _building_nss: 71 72 `Building NSS <#building_nss>`__ 73 -------------------------------- 74 75 .. container:: 76 77 NSS is built using `gyp <https://gyp.gsrc.io/>`__ and `ninja <https://ninja-build.org/>`__, or 78 with `make <https://www.gnu.org/software/make/>`__ on systems that don't have those tools. The 79 :ref:`mozilla_projects_nss_building` include more information. 80 81 Once the build is done, you can find the build output below directory dist/?, where ? will be a 82 name dynamically derived from your system's architecture. Exported header files for NSS 83 applications can be found in directory "include", library files in directory "lib", and the tools 84 in directory "bin". In order to run the tools, you should set your system environment to use the 85 libraries of your build from the "lib" directory, e.g., using the LD_LIBRARY_PATH or 86 DYLD_LIBRARY_PATH environment variable. 87 88 .. _running_the_nss_test_suite: 89 90 `Running the NSS test suite <#running_the_nss_test_suite>`__ 91 ------------------------------------------------------------ 92 93 .. container:: 94 95 This is an important part of development work, in order to ensure your changes don't introduce 96 regressions. When adding new features to NSS, tests for the new feature should be added as well. 97 98 You must build NSS prior to running the tests. After the build on your computer has succeeded, 99 before you can run the tests on your computer, it might be necessary to set additional 100 environment variables. The NSS tests will start TCP/IP server tools on your computer, and in 101 order for that to work, the NSS test suite needs to know which hostname can be used by client 102 tools to connect to the server tools. On machines that are configured with a hostname that has 103 been registered in your network's DNS, this should work automatically. In other environments (for 104 example in home networks), you could set the HOST and DOMSUF (for domain suffix) environment 105 variables to tell the NSS suite which hostname to use. As a test, it must be possible to 106 successfully use the command "ping $HOST.$DOMSUF" on your computer (ping reports receiving 107 replies). On many computers the variables HOST=localhost DOMSUF=localdomain works. In case you 108 built NSS in 64 bits, you need to set the USE_64 environment variable to 1 to run the tests. If 109 you get name resolution errors, try to disable IPv6 on the loopback device. 110 111 After you have set the required environment variables, use "cd nss/tests" and start the tests 112 using "./all.sh". The tests will take a while to complete; on a slow computer it could take a 113 couple of hours. 114 115 Once the test suite has completed, a summary will be printed that shows the number of failures. 116 You can find the test suite results in directory nss/../tests_results (i.e. the results directory 117 ends up next to the nss directory, not within it). Each test suite execution will create a new 118 subdirectory; you should clean them up from time to time. Inside the directory you'll find text 119 file output.log, which contains a detailed report of all tests being executed. In order to learn 120 about the details of test failures, search the file for the uppercase test FAILED. 121 122 If desired, it's possible to run only subsets of the tests. Read the contents of file all.sh to 123 learn how that works.