NSS sources building testing

  • Revision slug: NSS_Sources_Building_Testing
  • Revision title: NSS Sources Building Testing
  • Revision id: 439029
  • Created:
  • Creator: SarahWalrus
  • Is current revision? No
  • Comment

Revision Content

Getting the sourcecode of Network Security Services (NSS), how to build it, and how to run its test suite.

Getting sourcecode, and a quick overview

The easiest way is to download archives of NSS releases from Mozilla's FTP server. Find the directory that contains the highest version number. Because NSS depends on the base library NSPR, you should download the archive that combines both NSS and NSPR.

For historical reasons, the directory hierarchy starts with the "mozilla" prefix. The NSPR base library is located in directory mozilla/nsprpub. All of the following directories are part of the NSS sources:

  • mozilla/dbm
  • mozilla/security/dbm
  • mozilla/security/coreconf
  • mozilla/security/nss

Directory "coreconf" contains knowledge for cross platform building.  The "dbm" directories contain an implementation of the classic database file format used by NSS. The majority of NSS is located contained in the "nss" subdirectory, with the following ones or particular interest:

  • mozilla/security/nss/lib
    Contains all the library code that are used to create the runtime libraries used by applications
  • mozilla/security/nss/cmd
    Contains a set of various tool programs that are built using NSS. Several tools are general purpose and can be used to inspect and manipulate the storage files that software using the NSS library creates and modifies. Other tools are only used for testing purposes. However, all these tools are good examples how to write software that makes use of the NSS library.
  • mozilla/security/nss/test
    This directory contains the NSS test suite, that is routinely used to ensure that changes to NSS don't introduce regressions.

Some words regarding the difference between internal NSS code and exported interfaces. Software that would like to use the NSS library must use only the exported interfaces. These can be found by looking at the files with the .def file extension, inside the nss/lib directory hierarchy. Any C function that isn't contained in .def files is strictly for private use within NSS, and applications and test tools are not allowed to call them. For any functions that are listed in the .def files, NSS promises that the binary function interface (ABI) will remain stable.

If you are a software developer and intend to contribute enhancements to NSS, you should obtain the latest development snapshot of NSS is using "cvs". In order to get started, anonymous read-only access is sufficient, use the following comment

cvs -z3 -d :pserver:anonymous@cvs-mirror.mozilla.org:/cvsroot checkout mozilla/nsprpub mozilla/dbm mozilla/security/dbm mozilla/security/coreconf mozilla/security/nss

Building NSS

The build process is driven by Makefiles from console windows. Because of the cross platform portability requirements, the build might behave different from what you are used to. In particular, NSS doesn't use configure scripts. You may set environment variables to define which build variation you want.

On a Linux/Unix like system use the bash shell. On a Windows system, you must download the Windows Build package provided by the Mozilla.org project, which will give you a similar command line environment, sufficient for the purposes of building.

Make sure that NSPR and NSS sources are next to each other, below the same "mozilla/" parent directory. In other words, your mozilla/ directory should contain the subdirectories "dbm", "nsprpub" and "security". If you downloaded a combined nss-with-nspr source archive from the NSS release directory on the FTP server, it will be already be organized that way.

In order to start the build process, use "cd mozilla/security/nss" and execute "gmake nss_build_all".  By default this will produce a build in debug mode and for a 32 bit architecture. You may set the environment variable BUILD_OPT=1 to get an optimized build, and variable USE_64=1 to get a 64 bit build.

Once the build is done, you can find the build output below directory mozilla/dist/*.OBJ, where * will be a name dynamically derived from your system's architecture. Exported header files for NSS applications can be found in directory "include", library files in directory "lib", and the tools in directory "bin". In order to run the tools, you should set your system environment to use the libraries of your build from the "lib" directory, e.g. using the LD_LIBRARY_PATH environment variable.

The following page might have additional information of interest.

Running the NSS test suite

This is an important part of development work, in order to ensure your changes don't introduce regressions. When adding new features to NSS, tests for the new feature should be added as well.

You must build NSS prior to running the tests. After the build on your computer has succeeded, before you can run the tests on your computer, it might be necessary to  set additional environment variables. The NSS tests will start TCP/IP server tools on your computer, and in order for that to work, the NSS test suite needs to know which hostname can be used by client tools to connect to the server tools. On machines that are configured with a hostname that has been registered in your network's DNS, this should work automatically. In other environments (for example in home networks), you could set the HOST and DOMSUF (for domain suffix) environment variables to tell the NSS suite which hostname to use. As a test, it must be possible to succesfully use the command "ping $HOST.$DOMSUF" on your computer (ping reports receiving replies). On many computers the variables HOST=localhost DOMSUF=localdomain works. In case you built NSS in 64 bits, you need to set the USE_64 environment variable to 1 to run the tests.

After you have set the required environment variables, use "cd mozilla/security/nss/tests" and start the tests using "./all.sh". The tests will take a while to complete, on a slow computer it could take a couple of hours.

Once the test suite has completed, a summary will be printed that shows the number of failures. You can find the test suite results in directory mozilla/tests_results. Each test suite execution will create a new subdirectory, you should clean it up from time to time. Inside the directory you'll find text file output.log, which contains a detailed report of all tests being executed. In order to learn about the details of test failures, search the file for the uppercase test FAILED.

If desired, it's possible to run only subsets of the tests. Read the contents of file all.sh to learn how that works.

Revision Source

<p>Getting the sourcecode of <a href="https://developer.mozilla.org/en-US/docs/NSS" title="/en-US/docs/NSS">Network Security Services (NSS)</a>, how to build it, and how to run its test suite.</p>
<h2 id="Getting_Sourcecode.2C_and_a_quick_overview">Getting sourcecode, and a quick overview</h2>
<p>The easiest way is to download archives of NSS releases from <a href="ftp://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/" title="ftp://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/">Mozilla's FTP server</a>. Find the directory that contains the highest version number. Because NSS depends on the base library NSPR, you should download the archive that combines both NSS and NSPR.</p>
<p>For historical reasons, the directory hierarchy starts with the "mozilla" prefix. The NSPR base library is located in directory mozilla/nsprpub. All of the following directories are part of the NSS sources:</p>
<ul>
  <li>mozilla/dbm</li>
  <li>mozilla/security/dbm</li>
  <li>mozilla/security/coreconf</li>
  <li>mozilla/security/nss</li>
</ul>
<p>Directory "coreconf" contains knowledge for cross platform building.&nbsp; The "dbm" directories contain an implementation of the classic database file format used by NSS. The majority of NSS is located contained in the "nss" subdirectory, with the following ones or particular interest:</p>
<ul>
  <li>mozilla/security/nss/lib<br />
    Contains all the library code that are used to create the runtime libraries used by applications</li>
  <li>mozilla/security/nss/cmd<br />
    Contains a set of various tool programs that are built using NSS. Several tools are general purpose and can be used to inspect and manipulate the storage files that software using the NSS library creates and modifies. Other tools are only used for testing purposes. However, all these tools are good examples how to write software that makes use of the NSS library.</li>
  <li>mozilla/security/nss/test<br />
    This directory contains the NSS test suite, that is routinely used to ensure that changes to NSS don't introduce regressions.</li>
</ul>
<p>Some words regarding the difference between internal NSS code and exported interfaces. Software that would like to use the NSS library must use only the exported interfaces. These can be found by looking at the files with the .def file extension, inside the nss/lib directory hierarchy. Any C function that isn't contained in .def files is strictly for private use within NSS, and applications and test tools are not allowed to call them. For any functions that are listed in the .def files, NSS promises that the binary function interface (ABI) will remain stable.</p>
<p>If you are a software developer and intend to contribute enhancements to NSS, you should obtain the latest development snapshot of NSS is using "cvs". In order to get started, anonymous read-only access is sufficient, use the following comment</p>
<p><code>cvs -z3 -d :pserver:anonymous@cvs-mirror.mozilla.org:/cvsroot checkout mozilla/nsprpub mozilla/dbm mozilla/security/dbm mozilla/security/coreconf mozilla/security/nss</code></p>
<h2 id="Building_NSS">Building NSS</h2>
<p>The build process is driven by Makefiles from console windows. Because of the cross platform portability requirements, the build might behave different from what you are used to. In particular, NSS doesn't use configure scripts. You may set environment variables to define which build variation you want.</p>
<p>On a Linux/Unix like system use the bash shell. On a Windows system, you must download the Windows Build package provided by the Mozilla.org project, which will give you a similar command line environment, sufficient for the purposes of building.</p>
<p>Make sure that NSPR and NSS sources are next to each other, below the same "mozilla/" parent directory. In other words, your mozilla/ directory should contain the subdirectories "dbm", "nsprpub" and "security". If you downloaded a combined nss-with-nspr source archive from the NSS release directory on the FTP server, it will be already be organized that way.</p>
<p>In order to start the build process, use "cd mozilla/security/nss" and execute "gmake nss_build_all".&nbsp; By default this will produce a build in debug mode and for a 32 bit architecture. You may set the environment variable BUILD_OPT=1 to get an optimized build, and variable USE_64=1 to get a 64 bit build.</p>
<p>Once the build is done, you can find the build output below directory mozilla/dist/*.OBJ, where * will be a name dynamically derived from your system's architecture. Exported header files for NSS applications can be found in directory "include", library files in directory "lib", and the tools in directory "bin". In order to run the tools, you should set your system environment to use the libraries of your build from the "lib" directory, e.g. using the LD_LIBRARY_PATH environment variable.</p>
<p>The following page might have <a href="/en-US/docs/NSS_reference/Building_and_installing_NSS/Build_instructions" title="/en-US/docs/NSS_reference/Building_and_installing_NSS/Build_instructions">additional information of interest</a>.</p>
<h2 id="Running_the_NSS_test_suite">Running the NSS test suite</h2>
<p>This is an important part of development work, in order to ensure your changes don't introduce regressions. When adding new features to NSS, tests for the new feature should be added as well.</p>
<p>You must build NSS prior to running the tests. After the build on your computer has succeeded, before you can run the tests on your computer, it might be necessary to&nbsp; set additional environment variables. The NSS tests will start TCP/IP server tools on your computer, and in order for that to work, the NSS test suite needs to know which hostname can be used by client tools to connect to the server tools. On machines that are configured with a hostname that has been registered in your network's DNS, this should work automatically. In other environments (for example in home networks), you could set the HOST and DOMSUF (for domain suffix) environment variables to tell the NSS suite which hostname to use. As a test, it must be possible to succesfully use the command "ping $HOST.$DOMSUF" on your computer (ping reports receiving replies). On many computers the variables HOST=localhost DOMSUF=localdomain works. In case you built NSS in 64 bits, you need to set the USE_64 environment variable to 1 to run the tests.</p>
<p>After you have set the required environment variables, use "cd mozilla/security/nss/tests" and start the tests using "./all.sh". The tests will take a while to complete, on a slow computer it could take a couple of hours.</p>
<p>Once the test suite has completed, a summary will be printed that shows the number of failures. You can find the test suite results in directory mozilla/tests_results. Each test suite execution will create a new subdirectory, you should clean it up from time to time. Inside the directory you'll find text file output.log, which contains a detailed report of all tests being executed. In order to learn about the details of test failures, search the file for the uppercase test FAILED.</p>
<p>If desired, it's possible to run only subsets of the tests. Read the contents of file all.sh to learn how that works.</p>
Revert to this revision