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