@cindex @file{site-load.el}
You can specify additional files to preload by writing a library named
-@file{site-load.el} that loads them. You may need to increase the
-value of @code{PURESIZE}, in @file{src/puresize.h}, to make room for the
-additional files. (Try adding increments of 20000 until it is big
+@file{site-load.el} that loads them. You may need to increase the value
+of @code{PURESIZE}, in @file{src/puresize.h}, to make room for the
+additional data. (Try adding increments of 20000 until it is big
enough.) However, the advantage of preloading additional files
decreases as machines get faster. On modern machines, it is usually not
advisable.
+ After @file{loadup.el} reads @file{site-load.el}, it finds the
+documentation strings for primitive and preloaded functions (and
+variables) in the file @file{etc/DOC} where they are stored, by calling
+@code{Snarf-documentation} (@pxref{Accessing Documentation}).
+
@cindex @file{site-init.el}
You can specify other Lisp expressions to execute just before dumping
-by putting them in a library named @file{site-init.el}. However, if
-they might alter the behavior that users expect from an ordinary
-unmodified Emacs, it is better to put them in @file{default.el}, so that
-users can override them if they wish. @xref{Start-up Summary}.
-
- Before @file{loadup.el} dumps the new executable, it finds the
-documentation strings for primitive and preloaded functions (and
-variables) in the file where they are stored, by calling
-@code{Snarf-documentation} (@pxref{Accessing Documentation}). These
-strings were moved out of the @file{emacs} executable to make it
-smaller. @xref{Documentation Basics}.
+by putting them in a library named @file{site-init.el}. This file is
+executed after the documentation strings are found.
+
+ If you want to preload function or variable definitions, there are
+three ways you can do this and make their documentation strings
+accessible when you subsequently run Emacs:
+
+@itemize @bullet
+@item
+Arrange to scan these files when producing the @file{etc/DOC} file,
+and load them with @file{site-load.el}.
+
+@item
+Load the files with @file{site-init.el}, then copy the files into the
+installation directory for Lisp files when you install Emacs.
+
+@item
+Specify a non-@code{nil} value for
+@code{byte-compile-dynamic-docstrings} as a local variable in each these
+files, and load them with either @file{site-load.el} or
+@file{site-init.el}. (This method has the drawback that the
+documentation strings take up space in Emacs all the time.)
+@end itemize
+
+ It is not advisable to put anything in @file{site-load.el} or
+@file{site-init.el} that would alter any of the features that users
+expect in an ordinary unmodified Emacs. If you feel you must override
+normal features for your site, do it with @file{default.el}, so that
+users can override your changes if they wish. @xref{Start-up Summary}.
@defun dump-emacs to-file from-file
@cindex unexec
- This function dumps the current state of Emacs into an executable file
+This function dumps the current state of Emacs into an executable file
@var{to-file}. It takes symbols from @var{from-file} (this is normally
the executable file @file{temacs}).
-If you use this function in an Emacs that was already dumped, you must
-set @code{command-line-processed} to @code{nil} first for good results.
-@xref{Command Line Arguments}.
+If you want to use this function in an Emacs that was already dumped,
+you must run Emacs with @samp{-batch}.
@end defun
@deffn Command emacs-version
@example
@group
(emacs-version)
- @result{} "GNU Emacs 19.22.1 of Fri Feb 27 1994 \
-on slug (berkeley-unix)"
+ @result{} "GNU Emacs 19.29.1 (i386-debian-linux) \
+ of Tue Jun 6 1995 on balloon"
@end group
@end example
@end deffn
@defvar emacs-build-time
- The value of this variable is the time at which Emacs was built at the
+The value of this variable is the time at which Emacs was built at the
local site.
@example
@group
emacs-build-time
- @result{} "Fri Feb 27 14:55:57 1994"
+ @result{} "Tue Jun 6 14:55:57 1995"
@end group
@end example
@end defvar
@defvar emacs-version
The value of this variable is the version of Emacs being run. It is a
-string such as @code{"19.22.1"}.
+string such as @code{"19.29.1"}.
@end defvar
The following two variables did not exist before Emacs version 19.23,
@defvar emacs-major-version
The major version number of Emacs, as an integer. For Emacs version
-19.23, the value is 19.
+19.29, the value is 19.
@end defvar
@defvar emacs-minor-version
The minor version number of Emacs, as an integer. For Emacs version
-19.23, the value is 23.
+19.29, the value is 29.
@end defvar
@node Pure Storage, Garbage Collection, Building Emacs, GNU Emacs Internals
as symbols, but just returns them unchanged. It signals an error if
asked to copy markers.
-This function is used only while Emacs is being built and dumped; it is
-called only in the file @file{emacs/lisp/loaddefs.el}.
+This function is a no-op except while Emacs is being built and dumped;
+it is usually called only in the file @file{emacs/lisp/loaddefs.el}, but
+a few packages call it just in case you decide to preload them.
@end defun
@defvar pure-bytes-used
@end table
@end deffn
+@defopt garbage-collection-messages
+If this variable is non-@code{nil}, Emacs displays a message at the
+beginning and end of garbage collection. The default value is
+@code{nil}, meaning there are no such messages.
+@end defopt
+
@defopt gc-cons-threshold
The value of this variable is the number of bytes of storage that must
be allocated for Lisp objects after one garbage collection in order to
the threshold is exhausted, but only the next time the Lisp evaluator is
called.
-The initial threshold value is 100,000. If you specify a larger
+The initial threshold value is 300,000. If you specify a larger
value, garbage collection will happen less often. This reduces the
amount of time spent garbage collecting, but increases total memory use.
You may want to do this when running a program that creates lots of
@smallexample
@group
DEFUN ("or", For, Sor, 0, UNEVALLED, 0,
- "Eval args until one of them yields non-nil, then return that value.\n\
+ "Eval args until one of them yields non-nil; return that value.\n\
The remaining args are not evalled at all.\n\
@end group
@group
you use @code{GCPRO2}, you must declare @code{gcpro1} and @code{gcpro2}.
Alas, we can't explain all the tricky details here.
- Remember that you must never initialise external variables (whether
-static or not). If you do that, the linker will put the variable into
-the initialised data area of the process, which on many architectures
-becomes read-only when emacs is dumped (@pxref {Pure Storage}).
+ You must not use C initializers for static or global variables unless
+they are never written once Emacs is dumped. These variables with
+initializers are allocated in an area of memory that becomes read-only
+(on certain operating systems) as a result of dumping Emacs. @xref{Pure
+Storage}.
- Remember also that the keyword @code{static} is defined as nothing on
-many architectures whose linkers would put every static variable in the
-initialised data area, which becomes read-only after dumping. This
-means that you must never use static local variables, because on those
-architectures they would lose the @code{static} specifier and become
-automatic. Use static external variables instead.
+ Do not use static variables within functions---place all static
+variables at top level in the file. This is necessary because Emacs on
+some operating systems defines the keyword @code{static} as a null
+macro. (This definition is used because those systems put all variables
+declared static in a place that becomes read-only after dumping, whether
+they have initializers or not.)
Defining the C function is not enough to make a Lisp primitive
available; you must also create the Lisp symbol for the primitive and
that have special slots in the buffer object. (Those slots are omitted
from this table.) @xref{Buffer-Local Variables}.
+@item base_buffer
+This field holds the buffer's base buffer (if it is an indirect buffer),
+or @code{nil}.
+
@item keymap
This field holds the buffer's local keymap. @xref{Keymaps}.
The file descriptor for the terminal that the subprocess is using. (On
some systems, there is no need to record this, so the value is
@code{nil}.)
+
+@item tty_name
+The name of the terminal that the subprocess is using,
+or @code{nil} if it is using pipes.
@end table