summaryrefslogtreecommitdiffstats
path: root/docs/nspr/platforms.rst
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 19:33:14 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 19:33:14 +0000
commit36d22d82aa202bb199967e9512281e9a53db42c9 (patch)
tree105e8c98ddea1c1e4784a60a5a6410fa416be2de /docs/nspr/platforms.rst
parentInitial commit. (diff)
downloadfirefox-esr-36d22d82aa202bb199967e9512281e9a53db42c9.tar.xz
firefox-esr-36d22d82aa202bb199967e9512281e9a53db42c9.zip
Adding upstream version 115.7.0esr.upstream/115.7.0esrupstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
-rw-r--r--docs/nspr/platforms.rst145
1 files changed, 145 insertions, 0 deletions
diff --git a/docs/nspr/platforms.rst b/docs/nspr/platforms.rst
new file mode 100644
index 0000000000..6e251a4d71
--- /dev/null
+++ b/docs/nspr/platforms.rst
@@ -0,0 +1,145 @@
+NSPR platforms
+==============
+
+Build System and Supported Platforms
+------------------------------------
+
+NSPR has been implemented on over 20 platforms. A platform may have
+more than one implementation strategy of its multi threading and I/O
+facilities. This article explains the NSPR build system and how to
+specify a particular implementation strategy, compiler or compiler
+switches, or the target OS for your build on each platform.
+
+Implementation Strategies
+-------------------------
+
+Threads are at the core of NSPR, and the I/O functions are tied to the
+multi threading facilities because many I/O functions may block the
+calling threads. NSPR has multiple implementation strategies of its
+multi threading and I/O functions. The various implementation strategies
+can be organized into the hierarchy below:
+
+- **Classic NSPR** (This is our first code base, hence the term
+ "classic NSPR"):
+
+**Local threads only**: All threads are user-level threads implemented
+by NSPR.
+**Global threads only**: All threads are native threads supplied by the
+OS vendor. For example, Solaris UI (Unix International) threads and
+Win32 threads.
+**Combined**: NSPR multiplexes user-level threads on top of native,
+kernel-level threads. This is also called the MxN model. At present,
+there are three implementations of the combined model.
+
+- IRIX: sprocs + NSPR user-level threads
+- Windows NT: Win32 threads + NT fibers
+- **Pthreads-user**: kernel-level pthreads + NSPR user-level threads
+
+**Pthreads**: All threads are pthreads. The relevant code is in
+``mozilla/nsprpub/pr/src/pthreads`` (threads and I/O).
+Classic NSPR and pthreads have relatively disjoint code bases in the
+threads and I/O areas:
+
+- Classic NSPR: ``mozilla/nsprpub/pr/src/threads/combined`` (threads),
+ ``mozilla/nsprpub/pr/src/io`` (I/O)
+- Pthreads: ``mozilla/nsprpub/pr/src/pthreads`` (threads and I/O)
+
+Note that some files under ``mozilla/nsprpub/pr/src/io`` are shared by
+both classic NSPR and pthreads. Consult
+``mozilla/nsprpub/pr/src/Makefile`` for the definitive list of files
+used by each implementation strategy (see the definition of the makefile
+variable ``OBJS``).
+
+Compilers
+---------
+
+For ease of integration with third-party libraries, which may use native
+threads, NSPR uses the native threads whenever possible. As a result,
+native compilers are used to build NSPR on most platforms because they
+have better debugging support for native threads. The only exception is
+Solaris, where both cc and gcc are used.
+
+NSPR Build System
+-----------------
+
+NSPR build system is based on GNU make.
+We use GNU make 3.74 on Unix, but our makefiles should
+work fine under newer versions of GNU make.
+
+Every directory in NSPR has a makefile named ``Makefile``, which
+includes the makefile fragments in ``mozilla/nsprpub/config``. NSPR
+makefiles implement the common Makefile targets such as
+``export``, ``libs``, and ``install``. However, some makefiles targets
+are no-op in NSPR because they are not necessary for NSPR.
+
+To build NSPR, change directory to the root of our source tree
+``cd mozilla/nsprpub``
+and then issue the command
+``gmake``
+Make will recursively go into all the subdirectories and the right
+things will happen.
+
+The table below lists the common NSPR makefile targets.
+
++-----------------------------------+-----------------------------------+
+| ``all`` | The default target. Same as |
+| | ``export`` ``libs`` ``install``. |
++-----------------------------------+-----------------------------------+
+| ``export`` | Do a complete build. |
++-----------------------------------+-----------------------------------+
+| ``libs`` | No-op. |
++-----------------------------------+-----------------------------------+
+| ``install`` | No-op. |
++-----------------------------------+-----------------------------------+
+| ``depend`` | No-op. **This means that NSPR |
+| | makefiles do not have header file |
+| | dependencies.** |
++-----------------------------------+-----------------------------------+
+| ``clean`` | Remove ``.o`` files. |
++-----------------------------------+-----------------------------------+
+| ``clobber`` | Remove ``.o`` files, libraries, |
+| | and executable programs. |
++-----------------------------------+-----------------------------------+
+| ``realclean`` | Remove all generated files and |
+| | directories. |
++-----------------------------------+-----------------------------------+
+| ``clobber_all`` | Same as ``realclean``. |
++-----------------------------------+-----------------------------------+
+
+The table below lists common makefile variables that one can specify
+on the command line to customize a build..
+
++-----------------------------------+-----------------------------------+
+| ``BUILD_OPT`` | Optimized build (default: debug |
+| | build). |
++-----------------------------------+-----------------------------------+
+| ``OS_TARGET`` | Set to the target OS (``WIN95`` |
+| | or ``WIN16``) when doing |
+| | cross-compilation on NT (default: |
+| | same as the host OS). |
++-----------------------------------+-----------------------------------+
+| ``NS_USE_GCC`` | Use gcc and g++ (default: native |
+| | compilers). |
++-----------------------------------+-----------------------------------+
+| ``USE_PTHREADS`` | Build pthreads version. |
++-----------------------------------+-----------------------------------+
+| ``CLASSIC_NSPR`` | Build classic NSPR version |
+| | (usually local threads only). |
++-----------------------------------+-----------------------------------+
+| ``PTHREADS_USER`` | Build pthreads-user version. |
++-----------------------------------+-----------------------------------+
+| ``LOCAL_THREADS_ONLY`` | Build local threads only version. |
++-----------------------------------+-----------------------------------+
+| ``USE_DEBUG_RTL`` | On Win32, compile with ``/MDd`` |
+| | in the debug build (default: |
+| | ``/MD``). Optimized build always |
+| | uses ``/MD``. |
++-----------------------------------+-----------------------------------+
+| ``USE_N32`` | On IRIX, compile with ``-n32`` |
+| | (default: ``-32``). |
++-----------------------------------+-----------------------------------+
+| ``USE_IPV6`` | Enable IPv6. |
++-----------------------------------+-----------------------------------+
+| ``MOZILLA_CLIENT`` | Adjust NSPR build system for |
+| | Netscape Client (mozilla). |
++-----------------------------------+-----------------------------------+