Mercurial > hg > xemacs-beta

comparison man/lispref/building.texi @ 0:376386a54a3c r19-14

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r19-14
author cvs
date Mon, 13 Aug 2007 08:45:50 +0200
parents
children 859a2309aef8
comparison
equal deleted inserted replaced
-1:000000000000 0:376386a54a3c
1 @c -*-texinfo-*-
2 @c This is part of the XEmacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
4 @c See the file lispref.texi for copying conditions.
5 @setfilename ../../info/building.info
6 @node Building XEmacs and Object Allocation, Standard Errors, Tips, Top
7 @appendix Building XEmacs; Allocation of Objects
8
9 This chapter describes how the runnable XEmacs executable is dumped
10 with the preloaded Lisp libraries in it and how storage is allocated.
11
12 There is an entire separate document, the @cite{XEmacs Internals
13 Manual}, devoted to the internals of XEmacs from the perspective of the
14 C programmer. It contains much more detailed information about the
15 build process, the allocation and garbage-collection process, and other
16 aspects related to the internals of XEmacs.
17
18 @menu
19 * Building XEmacs:: How to preload Lisp libraries into XEmacs.
20 * Pure Storage:: A kludge to make preloaded Lisp functions sharable.
21 * Garbage Collection:: Reclaiming space for Lisp objects no longer used.
22 @end menu
23
24 @node Building XEmacs
25 @appendixsec Building XEmacs
26 @cindex building XEmacs
27 @pindex temacs
28
29 This section explains the steps involved in building the XEmacs
30 executable. You don't have to know this material to build and install
31 XEmacs, since the makefiles do all these things automatically. This
32 information is pertinent to XEmacs maintenance.
33
34 The @cite{XEmacs Internals Manual} contains more information about this.
35
36 Compilation of the C source files in the @file{src} directory
37 produces an executable file called @file{temacs}, also called a
38 @dfn{bare impure XEmacs}. It contains the XEmacs Lisp interpreter and I/O
39 routines, but not the editing commands.
40
41 @cindex @file{loadup.el}
42 Before XEmacs is actually usable, a number of Lisp files need to be
43 loaded. These define all the editing commands, plus most of the startup
44 code and many very basic Lisp primitives. This is accomplished by
45 loading the file @file{loadup.el}, which in turn loads all of the other
46 standardly-loaded Lisp files.
47
48 It takes a substantial time to load the standard Lisp files. Luckily,
49 you don't have to do this each time you run XEmacs; @file{temacs} can
50 dump out an executable program called @file{xemacs} that has these files
51 preloaded. @file{xemacs} starts more quickly because it does not need to
52 load the files. This is the XEmacs executable that is normally
53 installed.
54
55 To create @file{xemacs}, use the command @samp{temacs -batch -l loadup
56 dump}. The purpose of @samp{-batch} here is to tell @file{temacs} to run
57 in non-interactive, command-line mode. (@file{temacs} can @emph{only} run
58 in this fashion. Part of the code required to initialize frames and faces
59 is in Lisp, and must be loaded before XEmacs is able to create any frames.)
60 The argument @samp{dump} tells @file{loadup.el} to dump a new executable
61 named @file{xemacs}.
62
63 The dumping process is highly system-specific, and some operating
64 systems don't support dumping. On those systems, you must start XEmacs
65 with the @samp{temacs -batch -l loadup run-temacs} command each time you
66 use it. This takes a substantial time, but since you need to start
67 Emacs once a day at most---or once a week if you never log out---the
68 extra time is not too severe a problem. (In older versions of Emacs,
69 you started Emacs from @file{temacs} using @samp{temacs -l loadup}.)
70
71 @cindex runnable @file{temacs}
72 @cindex bootstrapping XEmacs from @file{temacs}
73 You are free to start XEmacs directly from @file{temacs} if you want,
74 even if there is already a dumped @file{xemacs}. Normally you wouldn't
75 want to do that; but the Makefiles do this when you rebuild XEmacs using
76 @samp{make all-elc}, which builds XEmacs and simultaneously compiles any
77 out-of-date Lisp files. (You need @file{xemacs} in order to compile Lisp
78 files. However, you also need the compiled Lisp files in order to dump
79 out @file{xemacs}. If both of these are missing or corrupted, you are
80 out of luck unless you're able to bootstrap @file{xemacs} from
81 @file{temacs}. Note that @samp{make all-elc} actually loads the
82 alternative loadup file @file{loadup-el.el}, which works like
83 @file{loadup.el} but disables the pure-copying process and forces
84 XEmacs to ignore any compiled Lisp files even if they exist.)
85
86 @cindex @file{site-load.el}
87 You can specify additional files to preload by writing a library named
88 @file{site-load.el} that loads them. You may need to increase the value
89 of @code{PURESIZE}, in @file{src/puresize.h}, to make room for the
90 additional files. You should @emph{not} modify this file directly,
91 however; instead, use the @samp{--puresize} configuration option. (If
92 you run out of pure space while dumping @file{xemacs}, you will be told
93 how much pure space you actually will need.) However, the advantage of
94 preloading additional files decreases as machines get faster. On modern
95 machines, it is often not advisable, especially if the Lisp code is
96 on a file system local to the machine running XEmacs.
97
98 @cindex @file{site-init.el}
99 You can specify other Lisp expressions to execute just before dumping
100 by putting them in a library named @file{site-init.el}. However, if
101 they might alter the behavior that users expect from an ordinary
102 unmodified XEmacs, it is better to put them in @file{default.el}, so that
103 users can override them if they wish. @xref{Start-up Summary}.
104
105 Before @file{loadup.el} dumps the new executable, it finds the
106 documentation strings for primitive and preloaded functions (and
107 variables) in the file where they are stored, by calling
108 @code{Snarf-documentation} (@pxref{Accessing Documentation}). These
109 strings were moved out of the @file{xemacs} executable to make it
110 smaller. @xref{Documentation Basics}.
111
112 @defun dump-emacs to-file from-file
113 @cindex unexec
114 This function dumps the current state of XEmacs into an executable file
115 @var{to-file}. It takes symbols from @var{from-file} (this is normally
116 the executable file @file{temacs}).
117
118 If you use this function in an XEmacs that was already dumped, you must
119 set @code{command-line-processed} to @code{nil} first for good results.
120 @xref{Command Line Arguments}.
121 @end defun
122
123 @defun run-emacs-from-temacs &rest args
124 This is the function that implements the @file{run-temacs} command-line
125 argument. It is called from @file{loadup.el} as appropriate. You should
126 most emphatically @emph{not} call this yourself; it will reinitialize
127 your XEmacs process and you'll be sorry.
128 @end defun
129
130 @deffn Command emacs-version
131 This function returns a string describing the version of XEmacs that is
132 running. It is useful to include this string in bug reports.
133
134 @example
135 @group
136 (emacs-version)
137 @result{} "XEmacs 19.14 [Lucid] (i586-unknown-linux1.2.13)
138 of Wed Mar 6 1996 on nene"
139 @end group
140 @end example
141
142 Called interactively, the function prints the same information in the
143 echo area.
144 @end deffn
145
146 @defvar emacs-build-time
147 The value of this variable is the time at which XEmacs was built at the
148 local site.
149
150 @example
151 @group
152 emacs-build-time
153 @result{} "Wed Mar 6 14:55:57 1996"
154 @end group
155 @end example
156 @end defvar
157
158 @defvar emacs-version
159 The value of this variable is the version of Emacs being run. It is a
160 string, e.g. @code{"19.14 XEmacs Lucid"}.
161 @end defvar
162
163 The following two variables did not exist before FSF GNU Emacs version
164 19.23 and XEmacs version 19.10, which reduces their usefulness at
165 present, but we hope they will be convenient in the future.
166
167 @defvar emacs-major-version
168 The major version number of Emacs, as an integer. For XEmacs version
169 19.14, the value is 19.
170 @end defvar
171
172 @defvar emacs-minor-version
173 The minor version number of Emacs, as an integer. For XEmacs version
174 19.14, the value is 14.
175 @end defvar
176
177 @node Pure Storage
178 @appendixsec Pure Storage
179 @cindex pure storage
180
181 XEmacs Lisp uses two kinds of storage for user-created Lisp objects:
182 @dfn{normal storage} and @dfn{pure storage}. Normal storage is where
183 all the new data created during an XEmacs session is kept; see the
184 following section for information on normal storage. Pure storage is
185 used for certain data in the preloaded standard Lisp files---data that
186 should never change during actual use of XEmacs.
187
188 Pure storage is allocated only while @file{temacs} is loading the
189 standard preloaded Lisp libraries. In the file @file{xemacs}, it is
190 marked as read-only (on operating systems that permit this), so that the
191 memory space can be shared by all the XEmacs jobs running on the machine
192 at once. Pure storage is not expandable; a fixed amount is allocated
193 when XEmacs is compiled, and if that is not sufficient for the preloaded
194 libraries, @file{temacs} aborts with an error message. If that happens,
195 you must increase the compilation parameter @code{PURESIZE} using the
196 @samp{--puresize} option to @file{configure}. This normally won't
197 happen unless you try to preload additional libraries or add features to
198 the standard ones.
199
200 @defun purecopy object
201 This function makes a copy of @var{object} in pure storage and returns
202 it. It copies strings by simply making a new string with the same
203 characters in pure storage. It recursively copies the contents of
204 vectors and cons cells. It does not make copies of other objects such
205 as symbols, but just returns them unchanged. It signals an error if
206 asked to copy markers.
207
208 This function is a no-op except while XEmacs is being built and dumped;
209 it is usually called only in the file
210 @file{xemacs/lisp/prim/loaddefs.el}, but a few packages call it just in
211 case you decide to preload them.
212 @end defun
213
214 @defvar pure-bytes-used
215 The value of this variable is the number of bytes of pure storage
216 allocated so far. Typically, in a dumped XEmacs, this number is very
217 close to the total amount of pure storage available---if it were not,
218 we would preallocate less.
219 @end defvar
220
221 @defvar purify-flag
222 This variable determines whether @code{defun} should make a copy of the
223 function definition in pure storage. If it is non-@code{nil}, then the
224 function definition is copied into pure storage.
225
226 This flag is @code{t} while loading all of the basic functions for
227 building XEmacs initially (allowing those functions to be sharable and
228 non-collectible). Dumping XEmacs as an executable always writes
229 @code{nil} in this variable, regardless of the value it actually has
230 before and after dumping.
231
232 You should not change this flag in a running XEmacs.
233 @end defvar
234
235 @node Garbage Collection
236 @appendixsec Garbage Collection
237 @cindex garbage collector
238
239 @cindex memory allocation
240 When a program creates a list or the user defines a new function (such
241 as by loading a library), that data is placed in normal storage. If
242 normal storage runs low, then XEmacs asks the operating system to
243 allocate more memory in blocks of 2k bytes. Each block is used for one
244 type of Lisp object, so symbols, cons cells, markers, etc., are
245 segregated in distinct blocks in memory. (Vectors, long strings,
246 buffers and certain other editing types, which are fairly large, are
247 allocated in individual blocks, one per object, while small strings are
248 packed into blocks of 8k bytes. [More correctly, a string is allocated
249 in two sections: a fixed size chunk containing the length, list of
250 extents, etc.; and a chunk containing the actual characters in the
251 string. It is this latter chunk that is either allocated individually
252 or packed into 8k blocks. The fixed size chunk is packed into 2k
253 blocks, as for conses, markers, etc.])
254
255 It is quite common to use some storage for a while, then release it by
256 (for example) killing a buffer or deleting the last pointer to an
257 object. XEmacs provides a @dfn{garbage collector} to reclaim this
258 abandoned storage. (This name is traditional, but ``garbage recycler''
259 might be a more intuitive metaphor for this facility.)
260
261 The garbage collector operates by finding and marking all Lisp objects
262 that are still accessible to Lisp programs. To begin with, it assumes
263 all the symbols, their values and associated function definitions, and
264 any data presently on the stack, are accessible. Any objects that can
265 be reached indirectly through other accessible objects are also
266 accessible.
267
268 When marking is finished, all objects still unmarked are garbage. No
269 matter what the Lisp program or the user does, it is impossible to refer
270 to them, since there is no longer a way to reach them. Their space
271 might as well be reused, since no one will miss them. The second
272 (``sweep'') phase of the garbage collector arranges to reuse them.
273
274 @cindex free list
275 The sweep phase puts unused cons cells onto a @dfn{free list} for
276 future allocation; likewise for symbols, markers, extents, events,
277 floats, compiled-function objects, and the fixed-size portion of
278 strings. It compacts the accessible small string-chars chunks so they
279 occupy fewer 8k blocks; then it frees the other 8k blocks. Vectors,
280 buffers, windows, and other large objects are individually allocated and
281 freed using @code{malloc} and @code{free}.
282
283 @cindex CL note---allocate more storage
284 @quotation
285 @b{Common Lisp note:} unlike other Lisps, XEmacs Lisp does not
286 call the garbage collector when the free list is empty. Instead, it
287 simply requests the operating system to allocate more storage, and
288 processing continues until @code{gc-cons-threshold} bytes have been
289 used.
290
291 This means that you can make sure that the garbage collector will not
292 run during a certain portion of a Lisp program by calling the garbage
293 collector explicitly just before it (provided that portion of the
294 program does not use so much space as to force a second garbage
295 collection).
296 @end quotation
297
298 @deffn Command garbage-collect
299 This command runs a garbage collection, and returns information on
300 the amount of space in use. (Garbage collection can also occur
301 spontaneously if you use more than @code{gc-cons-threshold} bytes of
302 Lisp data since the previous garbage collection.)
303
304 @code{garbage-collect} returns a list containing the following
305 information:
306
307 @example
308 @group
309 ((@var{used-conses} . @var{free-conses})
310 (@var{used-syms} . @var{free-syms})
311 @end group
312 (@var{used-markers} . @var{free-markers})
313 @var{used-string-chars}
314 @var{used-vector-slots}
315 (@var{plist}))
316
317 @group
318 @result{} ((73362 . 8325) (13718 . 164)
319 (5089 . 5098) 949121 118677
320 (conses-used 73362 conses-free 8329 cons-storage 658168
321 symbols-used 13718 symbols-free 164 symbol-storage 335216
322 bit-vectors-used 0 bit-vectors-total-length 0
323 bit-vector-storage 0 vectors-used 7882
324 vectors-total-length 118677 vector-storage 537764
325 compiled-functions-used 1336 compiled-functions-free 37
326 compiled-function-storage 44440 short-strings-used 28829
327 long-strings-used 2 strings-free 7722
328 short-strings-total-length 916657 short-string-storage 1179648
329 long-strings-total-length 32464 string-header-storage 441504
330 floats-used 3 floats-free 43 float-storage 2044 markers-used 5089
331 markers-free 5098 marker-storage 245280 events-used 103
332 events-free 835 event-storage 110656 extents-used 10519
333 extents-free 2718 extent-storage 372736
334 extent-auxiliarys-used 111 extent-auxiliarys-freed 3
335 extent-auxiliary-storage 4440 window-configurations-used 39
336 window-configurations-on-free-list 5
337 window-configurations-freed 10 window-configuration-storage 9492
338 popup-datas-used 3 popup-data-storage 72 toolbar-buttons-used 62
339 toolbar-button-storage 4960 toolbar-datas-used 12
340 toolbar-data-storage 240 symbol-value-buffer-locals-used 182
341 symbol-value-buffer-local-storage 5824
342 symbol-value-lisp-magics-used 22
343 symbol-value-lisp-magic-storage 1496
344 symbol-value-varaliases-used 43
345 symbol-value-varalias-storage 1032 opaque-lists-used 2
346 opaque-list-storage 48 color-instances-used 12
347 color-instance-storage 288 font-instances-used 5
348 font-instance-storage 180 opaques-used 11 opaque-storage 312
349 range-tables-used 1 range-table-storage 16 faces-used 34
350 face-storage 2584 glyphs-used 124 glyph-storage 4464
351 specifiers-used 775 specifier-storage 43869 weak-lists-used 786
352 weak-list-storage 18864 char-tables-used 40
353 char-table-storage 41920 buffers-used 25 buffer-storage 7000
354 extent-infos-used 457 extent-infos-freed 73
355 extent-info-storage 9140 keymaps-used 275 keymap-storage 12100
356 consoles-used 4 console-storage 384 command-builders-used 2
357 command-builder-storage 120 devices-used 2 device-storage 344
358 frames-used 3 frame-storage 624 image-instances-used 47
359 image-instance-storage 3008 windows-used 27 windows-freed 2
360 window-storage 9180 lcrecord-lists-used 15
361 lcrecord-list-storage 360 hashtables-used 631
362 hashtable-storage 25240 streams-used 1 streams-on-free-list 3
363 streams-freed 12 stream-storage 91))
364 @end group
365 @end example
366
367 Here is a table explaining each element:
368
369 @table @var
370 @item used-conses
371 The number of cons cells in use.
372
373 @item free-conses
374 The number of cons cells for which space has been obtained from the
375 operating system, but that are not currently being used.
376
377 @item used-syms
378 The number of symbols in use.
379
380 @item free-syms
381 The number of symbols for which space has been obtained from the
382 operating system, but that are not currently being used.
383
384 @item used-markers
385 The number of markers in use.
386
387 @item free-markers
388 The number of markers for which space has been obtained from the
389 operating system, but that are not currently being used.
390
391 @item used-string-chars
392 The total size of all strings, in characters.
393
394 @item used-vector-slots
395 The total number of elements of existing vectors.
396
397 @item plist
398 A list of alternating keyword/value pairs providing more detailed
399 information. (As you can see above, quite a lot of information is
400 provided.)
401 @ignore @c Different in XEmacs
402
403 @item used-floats
404 @c Emacs 19 feature
405 The number of floats in use.
406
407 @item free-floats
408 @c Emacs 19 feature
409 The number of floats for which space has been obtained from the
410 operating system, but that are not currently being used.
411 @end ignore
412 @end table
413 @end deffn
414
415 @defopt gc-cons-threshold
416 The value of this variable is the number of bytes of storage that must
417 be allocated for Lisp objects after one garbage collection in order to
418 trigger another garbage collection. A cons cell counts as eight bytes,
419 a string as one byte per character plus a few bytes of overhead, and so
420 on; space allocated to the contents of buffers does not count. Note
421 that the subsequent garbage collection does not happen immediately when
422 the threshold is exhausted, but only the next time the Lisp evaluator is
423 called.
424
425 The initial threshold value is 500,000. If you specify a larger
426 value, garbage collection will happen less often. This reduces the
427 amount of time spent garbage collecting, but increases total memory use.
428 You may want to do this when running a program that creates lots of
429 Lisp data.
430
431 You can make collections more frequent by specifying a smaller value,
432 down to 10,000. A value less than 10,000 will remain in effect only
433 until the subsequent garbage collection, at which time
434 @code{garbage-collect} will set the threshold back to 10,000. (This does
435 not apply if XEmacs was configured with @samp{--debug}. Therefore, be
436 careful when setting @code{gc-cons-threshold} in that case!)
437 @end defopt
438
439 @c Emacs 19 feature
440 @defun memory-limit
441 This function returns the address of the last byte XEmacs has allocated,
442 divided by 1024. We divide the value by 1024 to make sure it fits in a
443 Lisp integer.
444
445 You can use this to get a general idea of how your actions affect the
446 memory usage.
447 @end defun
448
449 @defvar pre-gc-hook
450 This is a normal hook to be run just before each garbage collection.
451 Interrupts, garbage collection, and errors are inhibited while this hook
452 runs, so be extremely careful in what you add here. In particular,
453 avoid consing, and do not interact with the user.
454 @end defvar
455
456 @defvar post-gc-hook
457 This is a normal hook to be run just after each garbage collection.
458 Interrupts, garbage collection, and errors are inhibited while this hook
459 runs, so be extremely careful in what you add here. In particular,
460 avoid consing, and do not interact with the user.
461 @end defvar
462
463 @defvar gc-message
464 This is a string to print to indicate that a garbage collection is in
465 progress. This is printed in the echo area. If the selected frame is
466 on a window system and @code{gc-pointer-glyph} specifies a value (i.e. a
467 pointer image instance) in the domain of the selected frame, the mouse
468 cursor will change instead of this message being printed.
469 @end defvar
470
471 @defvr Glyph gc-pointer-glyph
472 This holds the pointer glyph used to indicate that a garbage collection
473 is in progress. If the selected window is on a window system and this
474 glyph specifies a value (i.e. a pointer image instance) in the domain of
475 the selected window, the cursor will be changed as specified during
476 garbage collection. Otherwise, a message will be printed in the echo
477 area, as controlled by @code{gc-message}. @xref{Glyphs}.
478 @end defvr
479
480 If XEmacs was configured with @samp{--debug}, you can set the following
481 two variables to get direct information about all the allocation that
482 is happening in a segment of Lisp code.
483
484 @defvar debug-allocation
485 If non-zero, print out information to stderr about all objects
486 allocated.
487 @end defvar
488
489 @defvar debug-allocation-backtrace
490 Length (in stack frames) of short backtrace printed out by
491 @code{debug-allocation}.
492 @end defvar