the real runnable Emacs executable. These arguments direct
@file{temacs} to evaluate the Lisp files specified in the file
@file{loadup.el}. These files set up the normal Emacs editing
-environment, resulting in an Emacs which is still impure but no longer
+environment, resulting in an Emacs that is still impure but no longer
bare.
It takes a substantial time to load the standard Lisp files. Luckily,
you don't have to do this each time you run Emacs; @file{temacs} can
-dump out an executable program called @file{emacs} which has these files
+dump out an executable program called @file{emacs} that has these files
preloaded. @file{emacs} starts more quickly because it does not need to
load the files. This is the Emacs executable that is normally
installed.
@cindex @file{site-load.el}
You can specify additional files to preload by writing a library named
-@file{site-load.el} which 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,
convenient in the future.
@defvar emacs-major-version
-The major version number of Emacs, as an integer.
+The major version number of Emacs, as an integer. For Emacs version
+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
Emacs Lisp uses two kinds of storage for user-created Lisp objects:
@dfn{normal storage} and @dfn{pure storage}. Normal storage is where
-all the new data which is created during an Emacs session is kept; see
-the following section for information on normal storage. Pure storage
-is used for certain data in the preloaded standard Lisp files---data
-that should never change during actual use of Emacs.
+all the new data created during an Emacs session is kept; see the
+following section for information on normal storage. Pure storage is
+used for certain data in the preloaded standard Lisp files---data that
+should never change during actual use of Emacs.
Pure storage is allocated only while @file{temacs} is loading the
standard preloaded Lisp libraries. In the file @file{emacs}, it is
-marked as read-only (on operating systems which permit this), so that
+marked as read-only (on operating systems that permit this), so that
the memory space can be shared by all the Emacs jobs running on the
machine at once. Pure storage is not expandable; a fixed amount is
allocated when Emacs is compiled, and if that is not sufficient for the
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
The garbage collector operates by finding and marking all Lisp objects
that are still accessible to Lisp programs. To begin with, it assumes
all the symbols, their values and associated function definitions, and
-any data presently on the stack, are accessible. Any objects which can
+any data presently on the stack, are accessible. Any objects that can
be reached indirectly through other accessible objects are also
accessible.
When marking is finished, all objects still unmarked are garbage. No
matter what the Lisp program or the user does, it is impossible to refer
to them, since there is no longer a way to reach them. Their space
-might as well be reused, since no one will miss them. The second,
-``sweep'' phase of the garbage collector arranges to reuse them.
+might as well be reused, since no one will miss them. The second
+(``sweep'') phase of the garbage collector arranges to reuse them.
@cindex free list
The sweep phase puts unused cons cells onto a @dfn{free list}
for future allocation; likewise for symbols and markers. It compacts
the accessible strings so they occupy fewer 8k blocks; then it frees the
-other 8k blocks. Vectors, buffers, windows and other large objects are
+other 8k blocks. Vectors, buffers, windows, and other large objects are
individually allocated and freed using @code{malloc} and @code{free}.
@cindex CL note---allocate more storage
@quotation
-@b{Common Lisp note:} unlike other Lisps, GNU Emacs Lisp does not
+@b{Common Lisp note:} Unlike other Lisps, GNU Emacs Lisp does not
call the garbage collector when the free list is empty. Instead, it
simply requests the operating system to allocate more storage, and
processing continues until @code{gc-cons-threshold} bytes have been
@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 which creates lots of
+You may want to do this when running a program that creates lots of
Lisp data.
You can make collections more frequent by specifying a smaller value,
@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
name list that every C function must have, followed by ordinary C
declarations for the arguments. For a function with a fixed maximum
number of arguments, declare a C argument for each Lisp argument, and
-give them all type @code{Lisp_Object}. If the function has no upper
-limit on the number of arguments in Lisp, then in C it receives two
-arguments: the first is the number of Lisp arguments, and the second is
-the address of a block containing their values. They have types
-@code{int} and @w{@code{Lisp_Object *}}.
+give them all type @code{Lisp_Object}. When a Lisp function has no
+upper limit on the number of arguments, its implementation in C actually
+receives exactly two arguments: the first is the number of Lisp
+arguments, and the second is the address of a block containing their
+values. They have types @code{int} and @w{@code{Lisp_Object *}}.
Within the function @code{For} itself, note the use of the macros
@code{GCPRO1} and @code{UNGCPRO}. @code{GCPRO1} is used to ``protect''
you use @code{GCPRO2}, you must declare @code{gcpro1} and @code{gcpro2}.
Alas, we can't explain all the tricky details here.
+ 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}.
+
+ 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
store a suitable subr object in its function cell. The code looks like
of these functions are called, and add a call to
@code{syms_of_@var{filename}} there.
- This function @code{syms_of_@var{filename}} is also the place to
-define any C variables which are to be visible as Lisp variables.
+ The function @code{syms_of_@var{filename}} is also the place to define
+any C variables that are to be visible as Lisp variables.
@code{DEFVAR_LISP} makes a C variable of type @code{Lisp_Object} visible
in Lisp. @code{DEFVAR_INT} makes a C variable of type @code{int}
visible in Lisp with a value that is always an integer.
@table @code
@item name
-The buffer name is a string which names the buffer. It is guaranteed to
+The buffer name is a string that names the buffer. It is guaranteed to
be unique. @xref{Buffer Names}.
@item save_modified
@xref{Markers}.
@item backed_up
-This field is a flag which tells whether a backup file has been made
+This field is a flag that tells whether a backup file has been made
for the visited file of this buffer.
@item mark
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}.
Non-@code{nil} if this window is a minibuffer window.
@item buffer
-The buffer which the window is displaying. This may change often during
+The buffer that the window is displaying. This may change often during
the life of the window.
@item dedicated
selected; when it is not selected, it retains its previous value.
@item start
-he position in the buffer which is the first character to be displayed
+The position in the buffer that is the first character to be displayed
in the window.
@item force_start
Parent windows do not display buffers, and play little role in display
except to shape their child windows. Emacs Lisp programs usually have
no access to the parent windows; they operate on the windows at the
-leaves of the tree, that actually display buffers.
+leaves of the tree, which actually display buffers.
@item hscroll
This is the number of columns that the display in the window is scrolled
It is @code{nil} for a network connection.
@item mark
-A marker indicating the position of end of last output from this process
-inserted into the buffer. This is usually the end of the buffer.
+A marker indicating the position of the end of the last output from this
+process inserted into the buffer. This is often but not always the end
+of the buffer.
@item kill_without_query
If this is non-@code{nil}, killing Emacs while this process is still
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
HCoop / bpt / emacs.git / blobdiff