← Back to branch summary

~ubuntu-branches/ubuntu/breezy/gnustep-base/breezy

« back to all changes in this revision

Viewing changes to Documentation/gsdoc/Base.gsdoc

  • Committer: Bazaar Package Importer
  • Author(s): Eric Heintzmann
  • Date: 2005-04-17 00:14:38 UTC
  • mfrom: (1.2.1 upstream) (4 hoary)
  • mto: This revision was merged to the branch mainline in revision 5.
  • Revision ID: james.westby@ubuntu.com-20050417001438-enf0y07c9tku85z1
Tags: 1.10.3-1
New upstream release.

Show diffs side-by-side

added added

removed removed

Lines of Context:
Documentation/gsdoc/Base.gsdoc
1
 
<?xml version="1.0"?>
2
 
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 0.6.6//EN" "http://www.gnustep.org/gsdoc-0_6_6.xml">
3
 
<gsdoc base="Base">
4
 
  <head>
5
 
    <title>GNUstep Base</title>
6
 
    <author name="Richard Frith-Macdonald">
7
 
      <email address="rfm@gnu.org"/>
8
 
      <url url="http://www.gnustep.org/developers/whoiswho.html"/>
9
 
    </author>
10
 
    <version>$Revision: 1.15 $</version>
11
 
    <date>$Date: 2001/11/28 19:15:33 $</date>
12
 
  </head>
13
 
  <body>
14
 
    <chapter>
15
 
      <heading>Base</heading>
16
 
      <p>
17
 
        The GNUstep base library is a free software package implementing
18
 
        the API of the OpenStep Foundation Kit (tm), including later
19
 
        additions.
20
 
      </p>
21
 
      <section>
22
 
        <heading>Compatibility</heading>
23
 
        <p>
24
 
          GNUstep is generally compatible with the OpenStep specification and
25
 
          with recent developments of the MacOS (cocoa) API.  Where MacOS
26
 
          deviates from the OpenStep API, GNUstep generally attempts to
27
 
          support both versions.  In some cases the newer MacOS APIs are
28
 
          incompatible with OpenStep, and GNUstep usually supports the richer
29
 
          version.
30
 
        </p>
31
 
        <p>
32
 
          In order to deal with compatiblity issues, GNUstep uses two
33
 
          mechanisms - it provides conditionally compiled sections of
34
 
          the library header files, so that software can be built that
35
 
          will conform strictly to a particular API, and it provides
36
 
          user default settings to control the behavior of the library
37
 
          at runtime.
38
 
        </p>
39
 
        <subsect>
40
 
          <heading>Conditional compilation</heading>
41
 
          <p>
42
 
            Adding an option to a makefile to define one of the following
43
 
            preprocessor constants will modify the API visible to software
44
 
            being compiled -
45
 
          </p>
46
 
          <deflist>
47
 
            <term>NO_GNUSTEP</term>
48
 
            <desc>
49
 
              GNUstep specific extensions to the OpenStep and MacOS cocoa
50
 
              APIs are excluded from the headers.
51
 
            </desc>
52
 
            <term>STRICT_MACOS_X</term>
53
 
            <desc>
54
 
              Only methods and classes that are part of the MacOS cocoa
55
 
              API are made available in the headers.
56
 
            </desc>
57
 
            <term>STRICT_OPENSTEP</term>
58
 
            <desc>
59
 
              Only methods and classes that are part of the OpenStep
60
 
              specification are made available in the headers.
61
 
            </desc>
62
 
          </deflist>
63
 
        </subsect>
64
 
        <subsect>
65
 
          <heading>User defaults</heading>
66
 
          <deflist>
67
 
            <term>GSLogSyslog</term>
68
 
            <desc>
69
 
              <p>
70
 
                Setting the user default <code>GSLogSyslog</code> to
71
 
                <code>YES</code> will cause log/debug output to be sent to
72
 
                the syslog facility (on systems which support it), rather
73
 
                than to the standard error stream.  This is useful in
74
 
                environments where stderr has been re-used strangely for
75
 
                some reason.
76
 
              </p>
77
 
            </desc>
78
 
            <term>GSMacOSXCompatible</term>
79
 
            <desc>
80
 
              <p>
81
 
                Setting the user default <code>GSMacOSXCompatible</code> to
82
 
                <code>YES</code> will cause MacOS compatible behavior to be
83
 
                the default at runtime.  This default may however be overridden
84
 
                to provide more fine grained control of system behavior.
85
 
              </p>
86
 
            </desc>
87
 
            <term>GSOldStyleGeometry</term>
88
 
            <desc>
89
 
              <p>
90
 
                Specifies whether the functions for producing strings
91
 
                describing geometric structures (NSStringFromPoint(),
92
 
                NSStringFromSize(), and NSStringFromRect()) should produce
93
 
                strings conforming to the OpenStep specification or to
94
 
                MacOS-X behavior.  The functions for parsing those strings
95
 
                should cope with both cases anyway.
96
 
              </p>
97
 
            </desc>
98
 
            <term>NSWriteOldStylePropertyLists</term>
99
 
            <desc>
100
 
              <p>
101
 
                Specifies whether text property-list output should be in
102
 
                the default MacOS-X format (XML), or in the more human
103
 
                readable (but less powerful) original OpenStep format.
104
 
              </p>
105
 
              <p>
106
 
                Reading of property lists is supported in either format,
107
 
                but <em>only</em> if GNUstep is built with the libxml
108
 
                library (which is needed to handle XML parsing).
109
 
              </p>
110
 
              <p>
111
 
                NB. MacOS-X generates illegal XML for some strings - those
112
 
                which contain characters not legal in XML.  GNUstep always
113
 
                generates legal XML, at the cost of a certain degree of
114
 
                compatibility.  GNUstep XML property lists use a backslash
115
 
                to escape illegal chatracters, and consequently any string
116
 
                containing either a backslash or an illegal character will
117
 
                be written differently to the same string on MacOS-X.
118
 
              </p>
119
 
            </desc>
120
 
            <term>NSLanguages</term>
121
 
            <desc>
122
 
              <p>
123
 
              An array of strings that lists the users prefered languages,
124
 
              in order or preference. If not found the default is just 
125
 
              English.
126
 
              </p>
127
 
            </desc>
128
 
          </deflist>
129
 
        </subsect>
130
 
        <subsect>
131
 
          <heading>Environment variables</heading>
132
 
          <p>
133
 
            There are some environment variables used by GNUstep base, where
134
 
            there would be problems onbtaining data from the defaults asystem.
135
 
          </p>
136
 
          <deflist>
137
 
            <term>CRASH_ON_ABORT</term>
138
 
            <desc>
139
 
              <p>
140
 
                The default exception handler will either cause the program to
141
 
                simply terminate, or to crash - leaving a core dump.  The
142
 
                standard behavior is to leave a core dump if the library was
143
 
                built for debugging, and to simply exit if it was not.
144
 
              </p>
145
 
              <p>
146
 
                The CRASH_ON_ABORT environment variable can be used to
147
 
                override this behavior.  If this is defined to <em>NO</em>,
148
 
                <em>FALSE</em>, or <em>0</em> then the program will simply
149
 
                exit when an exception occurs.  Any other value of the
150
 
                variable will cause the program to generate a core dump.
151
 
              </p>
152
 
            </desc>
153
 
            <term>GNUSTEP_STRING_ENCODING</term>
154
 
            <desc>
155
 
              <p>
156
 
                This is used to specify the default encoding for 8-bit
157
 
                strings.  It defaults to NSISOLatin1StringEncoding, but
158
 
                may be any of the 8-bit encodings supported by your system
159
 
                (excluding multi-byte encodings).
160
 
              </p>
161
 
            </desc>
162
 
            <term>GNUSTEP_HOST_CPU</term>
163
 
            <desc>
164
 
              <p>
165
 
                Used in place of GNUSTEP_TARGET_CPU if the other is missing.
166
 
              </p>
167
 
            </desc>
168
 
            <term>GNUSTEP_HOST_DIR</term>
169
 
            <desc>
170
 
              <p>
171
 
                Used in place of GNUSTEP_TARGET_DIR if the other is missing.
172
 
              </p>
173
 
            </desc>
174
 
            <term>GNUSTEP_HOST_OS</term>
175
 
            <desc>
176
 
              <p>
177
 
                Used in place of GNUSTEP_TARGET_OS if the other is missing.
178
 
              </p>
179
 
            </desc>
180
 
            <term>GNUSTEP_LOCAL_ROOT</term>
181
 
            <desc>
182
 
              <p>
183
 
                Used to specify the GNUstep root directory for local
184
 
                (non-system) resources.  Typically all locally produced
185
 
                or contributed software is installed relative to this.
186
 
              </p>
187
 
            </desc>
188
 
            <term>GNUSTEP_NETWORK_ROOT</term>
189
 
            <desc>
190
 
              <p>
191
 
                Used to specify the GNUstep root directory for local
192
 
                (non-system) resources that are intended to be shared
193
 
                across a local network.  Typically this is an NFS exported
194
 
                directory shared by many machines.  It provides an
195
 
                alternative to GNUSTEP_LOCAL_ROOT.
196
 
              </p>
197
 
            </desc>
198
 
            <term>GNUSTEP_SYSTEM_ROOT</term>
199
 
            <desc>
200
 
              <p>
201
 
                Used to specify the GNUstep system root directory ... all
202
 
                system libraries, tools, applications, headers, resources
203
 
                in general are located relative to this.
204
 
              </p>
205
 
            </desc>
206
 
            <term>GNUSTEP_USER_ROOT</term>
207
 
            <desc>
208
 
              <p>
209
 
                Used to specify the GNUstep directory in which resources
210
 
                specific to the current user are located.
211
 
              </p>
212
 
            </desc>
213
 
            <term>GNUSTEP_TARGET_CPU</term>
214
 
            <desc>
215
 
              <p>
216
 
                Overrides the default value of the machine (hardware)
217
 
                name used on this system.
218
 
              </p>
219
 
            </desc>
220
 
            <term>GNUSTEP_TARGET_DIR</term>
221
 
            <desc>
222
 
              <p>
223
 
                Overrides the default path used to locate subdirectories
224
 
                for GNUstep binaries withing bundles and applications.
225
 
                This is normally equivalent to a path made up of the
226
 
                GNUSTEP_TARGET_CPU and GNUSTEP_TARGET_OS
227
 
              </p>
228
 
            </desc>
229
 
            <term>GNUSTEP_TARGET_OS</term>
230
 
            <desc>
231
 
              <p>
232
 
                Overrides the default value of the operating system
233
 
                name used on this system.
234
 
              </p>
235
 
            </desc>
236
 
            <term>GNUSTEP_TZ</term>
237
 
            <desc>
238
 
              <p>
239
 
                Used to specify the timezone to be used if there is no
240
 
                timezone specified in the user defaults system.
241
 
                The preferred
242
 
                mechanism is to use the 'Local Time Zone' value from the
243
 
                user defaults system.
244
 
              </p>
245
 
            </desc>
246
 
            <term>HOMEDRIVE</term>
247
 
            <desc>
248
 
              <p>
249
 
                Used on windoze to locate the home directory.
250
 
              </p>
251
 
            </desc>
252
 
            <term>HOMEPATH</term>
253
 
            <desc>
254
 
              <p>
255
 
                Used on windoze to locate the home directory.
256
 
              </p>
257
 
            </desc>
258
 
            <term>LANGUAGES</term>
259
 
            <desc>
260
 
              <p>
261
 
                If there is no NSLanguages user default set, and there is
262
 
                no language infromation available in the native system locale
263
 
                mechanism, then this environment variable is used to provide
264
 
                a list of the languages that the user prefers to use.
265
 
                languages listed in this variable must be separated by
266
 
                semicolons.
267
 
              </p>
268
 
            </desc>
269
 
            <term>LOGNAME</term>
270
 
            <desc>
271
 
              <p>
272
 
                This is used as the default value for the current user
273
 
                (as returned by the NSUserName() functions).  If it is not
274
 
                specified, or contains an illegal value, other methods are
275
 
                used to get the user name.
276
 
              </p>
277
 
            </desc>
278
 
            <term>LIBRARY_COMBO</term>
279
 
            <desc>
280
 
              <p>
281
 
                Used to override the default value of the combination
282
 
                of standard libraries used to build binaries.  This
283
 
                value locates the final subdirectory used to locate binaries.
284
 
              </p>
285
 
            </desc>
286
 
            <term>TZ</term>
287
 
            <desc>
288
 
              <p>
289
 
                Used to specify the timezone to be used if there is no
290
 
                timezone specified by any other mechanism.  The preferred
291
 
                mechanism is to use the 'Local Time Zone' value from the
292
 
                user defaults system.
293
 
              </p>
294
 
            </desc>
295
 
 
296
 
          </deflist>
297
 
        </subsect>
298
 
      </section>
299
 
      <section>
300
 
        <heading>The Foundation classes</heading>
301
 
        <list>
302
 
          <item><uref url="NSArchiver.html">NSArchiver</uref></item>
303
 
          <item><uref url="NSArray.html">NSArray</uref></item>
304
 
          <item><uref url="NSAssertionHandler.html">NSAssertionHandler</uref></item>
305
 
          <item><uref url="NSAttributedString.html">NSAttributedString</uref></item>
306
 
          <item><uref url="NSAutoreleasePool.html">NSAutoreleasePool</uref></item>
307
 
          <item><uref url="NSBundle.html">NSBundle</uref></item>
308
 
          <item><uref url="NSCalendarDate.html">NSCalendarDate</uref></item>
309
 
          <item><uref url="NSCharacterSet.html">NSCharacterSet</uref></item>
310
 
          <item><uref url="NSCoder.html">NSCoder</uref></item>
311
 
          <item><uref url="NSConditionLock.html">NSConditionLock</uref></item>
312
 
          <item><uref url="NSConnection.html">NSConnection</uref></item>
313
 
          <item><uref url="NSCountedSet.html">NSCountedSet</uref></item>
314
 
          <item><uref url="NSDate.html">NSDate</uref></item>
315
 
          <item><uref url="NSDateFormatter.html">NSDateFormatter</uref></item>
316
 
          <item><uref url="NSDecimalNumber.html">NSDecimalNumber</uref></item>
317
 
          <item><uref url="NSDecimalNumberHandler.html">NSDecimalNumberHandler</uref></item>
318
 
          <item><uref url="NSDeserializer.html">NSDeserializer</uref></item>
319
 
          <item><uref url="NSDictionary.html">NSDictionary</uref></item>
320
 
          <item><uref url="NSDirectoryEnumerator.html">NSDirectoryEnumerator</uref></item>
321
 
          <item><uref url="NSDistantObject.html">NSDistantObject</uref></item>
322
 
          <item><uref url="NSDistantObjectRequest.html">NSDistantObjectRequest</uref></item>
323
 
          <item><uref url="NSDistributedLock.html">NSDistributedLock</uref></item>
324
 
          <item><uref url="NSDistributedNotificationCenter.html">NSDistributedNotificationCenter</uref></item>
325
 
          <item><uref url="NSEnumerator.html">NSEnumerator</uref></item>
326
 
          <item><uref url="NSException.html">NSException</uref></item>
327
 
          <item><uref url="NSFileHandle.html">NSFileHandle</uref></item>
328
 
          <item><uref url="NSFileManager.html">NSFileManager</uref></item>
329
 
          <item><uref url="NSFormatter.html">NSFormatter</uref></item>
330
 
          <item><uref url="NSHost.html">NSHost</uref></item>
331
 
          <item><uref url="NSInvocation.html">NSInvocation</uref></item>
332
 
          <item><uref url="NSLock.html">NSLock</uref></item>
333
 
          <item><uref url="NSMethodSignature.html">NSMethodSignature</uref></item>
334
 
          <item><uref url="NSMutableArray.html">NSMutableArray</uref></item>
335
 
          <item><uref url="NSMutableAttributedString.html">NSMutableAttributedString</uref></item>
336
 
          <item><uref url="NSMutableCharacterSet.html">NSMutableCharacterSet</uref></item>
337
 
          <item><uref url="NSMutableData.html">NSMutableData</uref></item>
338
 
          <item><uref url="NSMutableDictionary.html">NSMutableDictionary</uref></item>
339
 
          <item><uref url="NSMutableSet.html">NSMutableSet</uref></item>
340
 
          <item><uref url="NSMutableString.html">NSMutableString</uref></item>
341
 
          <item><uref url="NSNotification.html">NSNotification</uref></item>
342
 
          <item><uref url="NSNotificationCenter.html">NSNotificationCenter</uref></item>
343
 
          <item><uref url="NSNotificationQueue.html">NSNotificationQueue</uref></item>
344
 
          <item><uref url="NSNull.html">NSNull</uref></item>
345
 
          <item><uref url="NSNumber.html">NSNumber</uref></item>
346
 
          <item><uref url="NSNumberFormatter.html">NSNumberFormatter</uref></item>
347
 
          <item><uref url="NSObject.html">NSObject</uref></item>
348
 
          <item><uref url="NSPipe.html">NSPipe</uref></item>
349
 
          <item><uref url="NSPort.html">NSPort</uref></item>
350
 
          <item><uref url="NSPortCoder.html">NSPortCoder</uref></item>
351
 
          <item><uref url="NSPortMessage.html">NSPortMessage</uref></item>
352
 
          <item><uref url="NSPortNameServer.html">NSPortNameServer</uref></item>
353
 
          <item><uref url="NSProcessInfo.html">NSProcessInfo</uref></item>
354
 
          <item><uref url="NSProtocolChecker.html">NSProtocolChecker</uref></item>
355
 
          <item><uref url="NSProxy.html">NSProxy</uref></item>
356
 
          <item><uref url="NSRecursiveLock.html">NSRecursiveLock</uref></item>
357
 
          <item><uref url="NSRunLoop.html">NSRunLoop</uref></item>
358
 
          <item><uref url="NSScanner.html">NSScanner</uref></item>
359
 
          <item><uref url="NSSerializer.html">NSSerializer</uref></item>
360
 
          <item><uref url="NSSet.html">NSSet</uref></item>
361
 
          <item><uref url="NSString.html">NSString</uref></item>
362
 
          <item><uref url="NSTask.html">NSTask</uref></item>
363
 
          <item><uref url="NSThread.html">NSThread</uref></item>
364
 
          <item><uref url="NSTimeZone.html">NSTimeZone</uref></item>
365
 
          <item><uref url="NSTimer.html">NSTimer</uref></item>
366
 
          <item><uref url="NSURL.html">NSURL</uref></item>
367
 
          <item><uref url="NSURLHandle.html">NSURLHandle</uref></item>
368
 
          <item><uref url="NSUnarchiver.html">NSUnarchiver</uref></item>
369
 
          <item><uref url="NSUndoManager.html">NSUndoManager</uref></item>
370
 
          <item><uref url="NSUserDefaults.html">NSUserDefaults</uref></item>
371
 
          <item><uref url="NSValue.html">NSValue</uref></item>
372
 
        </list>
373
 
      </section>
374
 
      <section>
375
 
        <heading>The OpenStep functions and types</heading>
376
 
        <list>
377
 
          <item><uref url="NSFunctions.html">Functions</uref></item>
378
 
        </list>
379
 
      </section>
380
 
      <section>
381
 
        <heading>The GNUstep extension classes</heading>
382
 
        <list>
383
 
          <item><uref url="GSMime.html">GSMime</uref></item>
384
 
          <item><uref url="GSXML.html">GSXML</uref></item>
385
 
        </list>
386
 
      </section>
387
 
    </chapter>
388
 
  </body>
389
 
</gsdoc>