comparison lispref/internals.texi @ 25751:467b88fab665

*** empty log message ***

25750:f1968a807f56

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
@var{to-file}.  It takes symbols from @var{from-file} (this is normally

@appendixsec Pure Storage
@cindex pure storage

  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 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

increase the compilation parameter @code{PURESIZE} in the file
@file{src/puresize.h}.  This normally won't happen unless you try to
preload additional libraries or add features to the standard ones.

@defun purecopy object
This function makes a copy of @var{object} in pure storage and returns
it.  It copies strings by simply making a new string with the same
characters in pure storage.  It recursively copies the contents of
vectors and cons cells.  It does not make copies of other objects such
as symbols, but just returns them unchanged.  It signals an error if
asked to copy markers.

must declare these explicitly, with type @code{struct gcpro}.  Thus, if
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

file, add to it a @code{syms_of_@var{filename}} (e.g.,
@code{syms_of_myfile}).  Then find the spot in @file{emacs.c} where all
of these functions are called, and add a call to
@code{syms_of_@var{filename}} there.

  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.
@code{DEFVAR_BOOL} makes a C variable of type @code{int} visible in Lisp
with a value that is either @code{t} or @code{nil}.

  If you define a file-scope C variable of type @code{Lisp_Object},
you must protect it for garbage-collection by calling @code{staticpro}
in @code{syms_of_@var{filename}}, like this:

@example
staticpro (&@var{variable});
@end example

  @file{eval.c} is a very good file to look through for examples;
@file{lisp.h} contains the definitions for some important macros and
functions.

@node Object Internals
@appendixsec Object Internals
@cindex object internals

  GNU Emacs Lisp manipulates many different types of data.  The actual

This field contains the time when the buffer was last saved, as an integer.
@xref{Buffer Modification}.

@item modtime
This field contains the modification time of the visited file.  It is
set when the file is written or read.  Every time the buffer is written
to the file, this field is compared to the modification time of the
file.  @xref{Buffer Modification}.

@item auto_save_modified
This field contains the time when the buffer was last auto-saved.

@item last_window_start

@item height
The height of the window, measured in lines.

@item width
The width of the window, measured in columns.

@item next
This is the window that is the next in the chain of siblings.  It is
@code{nil} in a window that is the rightmost or bottommost of a group of
siblings.

25751:467b88fab665

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 of 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{Startup Summary}.

@defun dump-emacs to-file from-file
@cindex unexec
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

@appendixsec Pure Storage
@cindex pure storage

  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 created during an Emacs session are 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

increase the compilation parameter @code{PURESIZE} in the file
@file{src/puresize.h}.  This normally won't happen unless you try to
preload additional libraries or add features to the standard ones.

@defun purecopy object
This function makes a copy in pure storage of @var{object}, and returns
it.  It copies a string by simply making a new string with the same
characters in pure storage.  It recursively copies the contents of
vectors and cons cells.  It does not make copies of other objects such
as symbols, but just returns them unchanged.  It signals an error if
asked to copy markers.

must declare these explicitly, with type @code{struct gcpro}.  Thus, if
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
the variables are never stored in 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

file, add to it a @code{syms_of_@var{filename}} (e.g.,
@code{syms_of_myfile}).  Then find the spot in @file{emacs.c} where all
of these functions are called, and add a call to
@code{syms_of_@var{filename}} there.

@vindex byte-boolean-vars
  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.
@code{DEFVAR_BOOL} makes a C variable of type @code{int} visible in Lisp
with a value that is either @code{t} or @code{nil}.  Note that variables
defined with @code{DEFVAR_BOOL} are automatically added to the list
@code{byte-boolean-vars} used by the byte compiler.

  If you define a file-scope C variable of type @code{Lisp_Object},
you must protect it from garbage-collection by calling @code{staticpro}
in @code{syms_of_@var{filename}}, like this:

@example
staticpro (&@var{variable});
@end example

  @file{eval.c} is a very good file to look through for examples;
@file{lisp.h} contains the definitions for some important macros and
functions.

  If you define a function which is side-effect free, update the code in
@file{byte-opt.el} which binds @code{side-effect-free-fns} and
@code{side-effect-and-error-free-fns} to include it.  This will help the
optimizer.

@node Object Internals
@appendixsec Object Internals
@cindex object internals

  GNU Emacs Lisp manipulates many different types of data.  The actual

This field contains the time when the buffer was last saved, as an integer.
@xref{Buffer Modification}.

@item modtime
This field contains the modification time of the visited file.  It is
set when the file is written or read.  Before writing the buffer into a
file, this field is compared to the modification time of the file to see
if the file has changed on disk.  @xref{Buffer Modification}.

@item auto_save_modified
This field contains the time when the buffer was last auto-saved.

@item last_window_start

@item height
The height of the window, measured in lines.

@item width
The width of the window, measured in columns.  This width includes the
scroll bar and fringes, and/or the separator line on the right of the
window (if any).

@item next
This is the window that is the next in the chain of siblings.  It is
@code{nil} in a window that is the rightmost or bottommost of a group of
siblings.