docs/nspr/platforms.rst

   1 NSPR platforms
   2 ==============
   3
   4 Build System and Supported Platforms
   5 ------------------------------------
   6
   7 NSPR has been implemented on over 20 platforms. A platform may have
   8 more than one implementation strategy of its multi threading and I/O
   9 facilities. This article explains the NSPR build system and how to
  10 specify a particular implementation strategy, compiler or compiler
  11 switches, or the target OS for your build on each platform.
  12
  13 Implementation Strategies
  14 -------------------------
  15
  16 Threads are at the core of NSPR, and the I/O functions are tied to the
  17 multi threading facilities because many I/O functions may block the
  18 calling threads. NSPR has multiple implementation strategies of its
  19 multi threading and I/O functions. The various implementation strategies
  20 can be organized into the hierarchy below:
  21
  22 -  **Classic NSPR** (This is our first code base, hence the term
  23    "classic NSPR"):
  24
  25 **Local threads only**: All threads are user-level threads implemented
  26 by NSPR.
  27 **Global threads only**: All threads are native threads supplied by the
  28 OS vendor. For example, Solaris UI (Unix International) threads and
  29 Win32 threads.
  30 **Combined**: NSPR multiplexes user-level threads on top of native,
  31 kernel-level threads. This is also called the MxN model. At present,
  32 there are three implementations of the combined model.
  33
  34 -  IRIX: sprocs + NSPR user-level threads
  35 -  Windows NT: Win32 threads + NT fibers
  36 -  **Pthreads-user**: kernel-level pthreads + NSPR user-level threads
  37
  38 **Pthreads**: All threads are pthreads. The relevant code is in
  39 ``mozilla/nsprpub/pr/src/pthreads`` (threads and I/O).
  40 Classic NSPR and pthreads have relatively disjoint code bases in the
  41 threads and I/O areas:
  42
  43 -  Classic NSPR: ``mozilla/nsprpub/pr/src/threads/combined`` (threads),
  44    ``mozilla/nsprpub/pr/src/io`` (I/O)
  45 -  Pthreads: ``mozilla/nsprpub/pr/src/pthreads`` (threads and I/O)
  46
  47 Note that some files under ``mozilla/nsprpub/pr/src/io`` are shared by
  48 both classic NSPR and pthreads. Consult
  49 ``mozilla/nsprpub/pr/src/Makefile`` for the definitive list of files
  50 used by each implementation strategy (see the definition of the makefile
  51 variable ``OBJS``).
  52
  53 Compilers
  54 ---------
  55
  56 For ease of integration with third-party libraries, which may use native
  57 threads, NSPR uses the native threads whenever possible. As a result,
  58 native compilers are used to build NSPR on most platforms because they
  59 have better debugging support for native threads. The only exception is
  60 Solaris, where both cc and gcc are used.
  61
  62 NSPR Build System
  63 -----------------
  64
  65 NSPR build system is based on GNU make.
  66 We use GNU make 3.74 on Unix, but our makefiles should
  67 work fine under newer versions of GNU make.
  68
  69 Every directory in NSPR has a makefile named ``Makefile``, which
  70 includes the makefile fragments in ``mozilla/nsprpub/config``. NSPR
  71 makefiles implement the common Makefile targets such as
  72 ``export``, ``libs``, and ``install``. However, some makefiles targets
  73 are no-op in NSPR because they are not necessary for NSPR.
  74
  75 To build NSPR, change directory to the root of our source tree
  76 ``cd mozilla/nsprpub``
  77 and then issue the command
  78 ``gmake``
  79 Make will recursively go into all the subdirectories and the right
  80 things will happen.
  81
  82 The table below lists the common NSPR makefile targets.
  83
  84 +-----------------------------------+-----------------------------------+
  85 | ``all``                           | The default target. Same as       |
  86 |                                   | ``export`` ``libs`` ``install``.  |
  87 +-----------------------------------+-----------------------------------+
  88 | ``export``                        | Do a complete build.              |
  89 +-----------------------------------+-----------------------------------+
  90 | ``libs``                          | No-op.                            |
  91 +-----------------------------------+-----------------------------------+
  92 | ``install``                       | No-op.                            |
  93 +-----------------------------------+-----------------------------------+
  94 | ``depend``                        | No-op. **This means that NSPR     |
  95 |                                   | makefiles do not have header file |
  96 |                                   | dependencies.**                   |
  97 +-----------------------------------+-----------------------------------+
  98 | ``clean``                         | Remove ``.o`` files.              |
  99 +-----------------------------------+-----------------------------------+
 100 | ``clobber``                       | Remove ``.o`` files, libraries,   |
 101 |                                   | and executable programs.          |
 102 +-----------------------------------+-----------------------------------+
 103 | ``realclean``                     | Remove all generated files and    |
 104 |                                   | directories.                      |
 105 +-----------------------------------+-----------------------------------+
 106 | ``clobber_all``                   | Same as ``realclean``.            |
 107 +-----------------------------------+-----------------------------------+
 108
 109 The table below lists common makefile variables that one can specify
 110 on the command line to customize a build..
 111
 112 +-----------------------------------+-----------------------------------+
 113 | ``BUILD_OPT``                     | Optimized build (default: debug   |
 114 |                                   | build).                           |
 115 +-----------------------------------+-----------------------------------+
 116 | ``OS_TARGET``                     | Set to the target OS (``WIN95``   |
 117 |                                   | or ``WIN16``) when doing          |
 118 |                                   | cross-compilation on NT (default: |
 119 |                                   | same as the host OS).             |
 120 +-----------------------------------+-----------------------------------+
 121 | ``NS_USE_GCC``                    | Use gcc and g++ (default: native  |
 122 |                                   | compilers).                       |
 123 +-----------------------------------+-----------------------------------+
 124 | ``USE_PTHREADS``                  | Build pthreads version.           |
 125 +-----------------------------------+-----------------------------------+
 126 | ``CLASSIC_NSPR``                  | Build classic NSPR version        |
 127 |                                   | (usually local threads only).     |
 128 +-----------------------------------+-----------------------------------+
 129 | ``PTHREADS_USER``                 | Build pthreads-user version.      |
 130 +-----------------------------------+-----------------------------------+
 131 | ``LOCAL_THREADS_ONLY``            | Build local threads only version. |
 132 +-----------------------------------+-----------------------------------+
 133 | ``USE_DEBUG_RTL``                 | On Win32, compile with ``/MDd``   |
 134 |                                   | in the debug build (default:      |
 135 |                                   | ``/MD``). Optimized build always  |
 136 |                                   | uses ``/MD``.                     |
 137 +-----------------------------------+-----------------------------------+
 138 | ``USE_N32``                       | On IRIX, compile with ``-n32``    |
 139 |                                   | (default: ``-32``).               |
 140 +-----------------------------------+-----------------------------------+
 141 | ``USE_IPV6``                      | Enable IPv6.                      |
 142 +-----------------------------------+-----------------------------------+
 143 | ``MOZILLA_CLIENT``                | Adjust NSPR build system for      |
 144 |                                   | Netscape Client (mozilla).        |
 145 +-----------------------------------+-----------------------------------+