Netscape Portable Runtime
Netscape Portable Runtime (NSPR) provides a platform-neutral API for system level and libc like functions. The API is used in the Mozilla client, many of Netscape/AOL/iPlanet's and other software offerings.
Read more about NSPR. This topic describes, in general terms, the goals of NSPR and a bit about how it does it. For a more complete description of NSPR, keep reading.
Contents
Status -- The current scoop on the NSPR
project.
Documentation and Training --
Learn to use NSPR to build your application.
The NSPR Reference -- A programmer's reference
to the NSPR API.
Technical Notes -- Technical
reports useful to application developers and NSPR maintainers.
Training Materials -- Other materials
usable for learning to use NSPR's API
Engineering Practices -- Tools
of the trade. What you need to know to maintain, change, build, release,
and contribute to NSPR.
Checkout and Build -- How to checkout
and build from source.
Testing NSPR -- How to build and run the
NSPR test suite.
NSPR Contributor's Guide -- So, you
want to write code for NSPR?
Release Engineering Guide --
Engineering practices for NSPR releases.
Contacts & Contributors --
Who maintains NSPR today. Identify past contributors to NSPR.
Status
The current release of NSPR is 4.6.5. See NSPR Release Notes for more information.
Pre-built binaries for Netscape/AOL/iPlanet supported platforms and some mozilla community built platforms may be downloaded from ftp://ftp.mozilla.org/pub/mozilla.org/nspr/releases .
The newsgroup mozilla.dev.tech.nspr is the place to ask questions and to follow NSPR discussions and announcements.
Bugs, features and other activity on NSPR are tracked via Bugzilla. Use the product name "NSPR" for submitting a bug report.
The NSPR maintainers do not guarantee the tip of the NSPR source tree to build or run at any instant in time; the tip of the tree is the development base. If you want to build NSPR yourself, use a tagged checkout.
Documentation and Training
NSPR provides several items of documentation. These are the "NSPR Reference", some Technical Notes, and other traing materials.
NSPR Reference
The NSPR Reference describes each API public macro, structure and function in the NSPR API. It is intended to be the definitive reference.
At this writing (19-Sep-2000) the NSPR Reference is a combination of hand written HTML and generated HTML. Some parts of the NSPR Reference are maintained using FrameMaker and are exported to HTML. ... Don't ask. ... Moving forward, the entire NSPR Reference will be maintained using FrameMaker and exported to HTML. If you need to make documentation suggestions and/or corrections, please submit a Bugzilla report.
Technical Notes
There are several Tech-Notes applicable to NSPR. These Tech-Notes provide usage information and hints to developers using or maintaining NSPR.
| Build System and Supported Platforms | NSPR uses common build technology across all platforms. This paper describes features of the build system and makefile macros controlling the build process. A table showing platforms that NSPR is known to run on with notes useful to maintainers. |
| Abrupt Exit | NSPR provides no "thread kill" interface. This paper discusses the reason why NSPR does not provide a thread kill and offers suggestions for working without this ill-concieved concept. |
| Automatic Variables and Threads | Passing the address of an automatic storage class variable (on the stack) can make for very nasty bugs in a multithreaded environment. This paper shows you how much trouble you can get into and what you should do to avoid these pitfalls. |
| What about fork() | Using fork() can behave strangely from one Unix to another. This paper describes some of the differences and offers techniques for consistent behavior across platforms. |
| About Non-Blocking I/O | NSPR was originally intended to offer only blocking socket I/O. For some good reasons, non-blocking I/O was added later. This paper describes the non-blocking model. |
| NT's handling of I/O timeouts is ... ummm ... less than optimum. | When an I/O operation times out on Windows NT, the socket becomes "unusable" and must be closed. This paper describes this phenomena and provides techniques for dealing with this ... anomaly. |
| Optimizing your application for NSPR | Providing a cross-platform API for Windows, Unix, Mac, et.al. is difficult. Trade-offs have to be made among performance, feasability, feature, and objects-of-least-astonishment. This paper describes some techniques that when applied to the design of your application will ensure reasonable results across all platforms. |
| Porting to NSPR to new platforms | Porting NSPR to most Unix platforms is not difficult. Porting NSPR to other environments can be problematic. This Tech-Note provides some help in making your port. |
| NSPR poll method | NSPR has a poll method for PRFileDesc. The poll method is usually used by the PR_Poll function behind the scene, but it is also possible to use the poll method directly. This Tech-Note describes the poll method, which is not documented in the NSPR Reference. |
Training Materials
NSPR does not provide extensive training. The following topics offer some guidance, beyond the NSPR Reference and Technical Notes on how to use the NSPR API.
NSPR Test Cases as Examples
The source tree for NSPR contains a set of test cases in the directory mozilla/nsprpub/pr/tests. Many of the programs in this directory show good examples of how to use the NSPR API elements together to obtain a coherent working application program. See also: Testing NSPR.
NSPR Overview slides
There are some Microsoft Powerpoint slides that were used in an NSPR overview tutorial in 1999.
Programming Threads Using NSPR slides
This set of Microsoft Powerpoint slides provides a good tutorial on using condition variables as a thread synchronization method. Condition variables are easy to misuse, for the uninitiated, but provide for a flexible and powerful method of thread synchronization.
Engineering Practices
Checkout and Build
In general, the NSPR team would prefer that you use a binary release of NSPR, especially if your interest is as a user of the API only. If you are a maintainer, or want to contribute to NSPR, then here is the procedure for checking out and building NSPR.
Testing NSPR
NSPR provides a fairly large test suite. Read more about it.
NSPR Contributor's Guide
So, you think you have something to contribute to NSPR? We sure could use your help. To help you help us, we are providing some guidelines that we believe are important to maintain the goals and stability of NSPR.
NSPR Release Engineering Guide
The NSPR Release Engineering Guide is primarily for the NSPR maintainers. It describes the steps required for building, testing and releasing NSPR for Netscape/AOL/iPlanet. Don't go here unless you really, really need to know.
Contacts and Contributors
NSPR is maintained by Wan-Teh Chang and Darin Fisher. Wan-Teh has been with the project since 1996. Darin has been with the project since 2003.
Alan Freier, Srinivas Lingutla, Lawrence Hardiman, Prashant Patel, and Mike Belshe have been major contributors to NSPR.
Chris Seawood implemented the current autoconf-based build system.
There are numerous other contributors. My apology for not including a complete list here.