@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1993, 1998-1999, 2001-2015 Free Software
+@c Copyright (C) 1990-1993, 1998-1999, 2001-2016 Free Software
@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node GNU Emacs Internals
Emacs, since the makefiles do all these things automatically. This
information is pertinent to Emacs developers.
- Compilation of the C source files in the @file{src} directory
+ Building Emacs requires GNU Make version 3.81 or later.
+
+ Compilation of the C source files in the @file{src} directory
produces an executable file called @file{temacs}, also called a
@dfn{bare impure Emacs}. It contains the Emacs Lisp interpreter and
I/O routines, but not the editing commands.
and are not able to implement dumping, then Emacs must load
@file{loadup.el} each time it starts.
+@cindex build details
+@cindex deterministic build
+@cindex @option{--disable-build-details} option to @command{configure}
+ By default the dumped @file{emacs} executable records details such
+as the build time and host name. Use the
+@option{--disable-build-details} option of @command{configure} to
+suppress these details, so that building and installing Emacs twice
+from the same sources is more likely to result in identical copies of
+Emacs.
+
@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 rebuild Emacs
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.
+(sweep) phase of the garbage collector arranges to reuse them.
@c ??? Maybe add something describing weak hash tables here?
@file{eval.c}. (An ordinary function would have the same general
appearance.)
-@cindex garbage collection protection
@smallexample
@group
DEFUN ("or", For, Sor, 0, UNEVALLED, 0,
If all args return nil, return nil.
@end group
@group
-usage: (or CONDITIONS ...) */)
+usage: (or CONDITIONS...) */)
(Lisp_Object args)
@{
- register Lisp_Object val = Qnil;
- struct gcpro gcpro1;
-@end group
-
-@group
- GCPRO1 (args);
+ Lisp_Object val = Qnil;
@end group
@group
if (!NILP (val))
break;
args = XCDR (args);
+ QUIT;
@}
@end group
@group
- UNGCPRO;
return val;
@}
@end group
the type explicitly using a suitable predicate (@pxref{Type Predicates}).
@cindex type checking internals
-@cindex @code{GCPRO} and @code{UNGCPRO}
+@cindex garbage collection protection
@cindex protect C variables from garbage collection
- Within the function @code{For} itself, note the use of the macros
-@code{GCPRO1} and @code{UNGCPRO}. These macros are defined for the
-sake of the few platforms which do not use Emacs' default
-stack-marking garbage collector. The @code{GCPRO1} macro ``protects''
-a variable from garbage collection, explicitly informing the garbage
-collector that that variable and all its contents must be as
-accessible. GC protection is necessary in any function which can
-perform Lisp evaluation by calling @code{eval_sub} or @code{Feval} as
-a subroutine, either directly or indirectly.
-
- It suffices to ensure that at least one pointer to each object is
-GC-protected. Thus, a particular local variable can do without
-protection if it is certain that the object it points to will be
-preserved by some other pointer (such as another local variable that
-has a @code{GCPRO}). Otherwise, the local variable needs a
-@code{GCPRO}.
-
- The macro @code{GCPRO1} protects just one local variable. If you
-want to protect two variables, use @code{GCPRO2} instead; repeating
-@code{GCPRO1} will not work. Macros @code{GCPRO3}, @code{GCPRO4},
-@code{GCPRO5}, and @code{GCPRO6} also exist. All these macros
-implicitly use local variables such as @code{gcpro1}; you must declare
-these explicitly, with type @code{struct gcpro}. Thus, if you use
-@code{GCPRO2}, you must declare @code{gcpro1} and @code{gcpro2}.
-
- @code{UNGCPRO} cancels the protection of the variables that are
-protected in the current function. It is necessary to do this
-explicitly.
+ Within the function @code{For} itself, the local variable
+@code{args} refers to objects controlled by Emacs's stack-marking
+garbage collector. Although the garbage collector does not reclaim
+objects reachable from C @code{Lisp_Object} stack variables, it may
+move non-object components of an object, such as string contents; so
+functions that access non-object components must take care to refetch
+their addresses after performing Lisp evaluation. Lisp evaluation can
+occur via calls to @code{eval_sub} or @code{Feval}, either directly or
+indirectly.
+
+@cindex @code{QUIT}, use in Lisp primitives
+ Note the call to the @code{QUIT} macro inside the loop: this macro
+checks whether the user pressed @kbd{C-g}, and if so, aborts the
+processing. You should do that in any loop that can potentially
+require a large number of iterations; in this case, the list of
+arguments could be very long. This increases Emacs responsiveness and
+improves user experience.
You must not use C initializers for static or global variables unless
the variables are never written once Emacs is dumped. These variables
@group
switch (coordinates_in_window (w, x, y))
@{
- case ON_NOTHING: /* NOT in window at all. */
+ case ON_NOTHING: /* NOT in window at all. */
return Qnil;
@end group
...
@group
- case ON_MODE_LINE: /* In mode line of window. */
+ case ON_MODE_LINE: /* In mode line of window. */
return Qmode_line;
@end group
arguments, in C it takes two: the number of Lisp-level arguments, and a
one-dimensional array containing their values. The first Lisp-level
argument is the Lisp function to call, and the rest are the arguments to
-pass to it. Since @code{Ffuncall} can call the evaluator, you must
-protect pointers from garbage collection around the call to
-@code{Ffuncall}.
+pass to it.
The C functions @code{call0}, @code{call1}, @code{call2}, and so on,
provide handy ways to call a Lisp function conveniently with a fixed
no access to the parent windows; they operate on the windows at the
leaves of the tree, which actually display buffers.
-@c FIXME: These two slots and the `buffer' slot below were replaced
-@c with a single slot `contents' on 2013-03-28. --xfq
+@c FIXME: These two slots and the 'buffer' slot below were replaced
+@c with a single slot 'contents' on 2013-03-28. --xfq
@item hchild
@itemx vchild
These fields contain the window's leftmost child and its topmost child
in this window.
@item last_had_star
-A non-@code{nil} value means the window's buffer was ``modified'' when the
+A non-@code{nil} value means the window's buffer was modified when the
window was last updated.
@item vertical_scroll_bar
Do not assume that signed integer arithmetic wraps around on overflow.
This is no longer true of Emacs porting targets: signed integer
overflow has undefined behavior in practice, and can dump core or
-even cause earlier or later code to behave ``illogically''. Unsigned
+even cause earlier or later code to behave illogically. Unsigned
overflow does wrap around reliably, modulo a power of two.
@item
of @code{intptr_t}).
@item
-Prefer @code{int} for Emacs character codes, in the range 0 ..@: 0x3FFFFF.
+Prefer @code{int} for Emacs character codes, in the range 0 ..@: 0x3FFFFF@.
More generally, prefer @code{int} for integers known to be in
@code{int} range, e.g., screen column counts.