platforms.rst (7668B)
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 +-----------------------------------+-----------------------------------+