Github/emacs
2
0
Fork 1
mirror of git://git.sv.gnu.org/emacs.git synced 2026-02-16 17:24:23 +00:00
Code Issues Projects Releases Packages Wiki Activity

entered into RCS

Browse source
This commit is contained in:
Richard M. Stallman 1994-04-30 01:38:51 +00:00
parent f06df5635f
commit 78c71a989d
2 changed files with 58 additions and 45 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

42
lispref/compile.texi
View file

@ -86,9 +86,9 @@ the @code{byte-compile} function. You can compile a whole file with
@code{byte-compile-file}, or several files with
@code{byte-recompile-directory} or @code{batch-byte-compile}.
When you run the byte compiler, you may get warnings in a buffer called
@samp{*Compile-Log*}. These report usage in your program that suggest a
problem, but are not necessarily erroneous.
When you run the byte compiler, you may get warnings in a buffer
called @samp{*Compile-Log*}. These report things in your program that
suggest a problem but are not necessarily erroneous.
@cindex macro compilation
Be careful when byte-compiling code that uses macros. Macro calls are
@ -97,7 +97,7 @@ for proper compilation. For more details, see @ref{Compiling Macros}.
Normally, compiling a file does not evaluate the file's contents or
load the file. But it does execute any @code{require} calls at
top-level in the file. One way to ensure that necessary macro
top level in the file. One way to ensure that necessary macro
definitions are available during compilation is to require the file that
defines them. @xref{Features}.
@ -201,7 +201,7 @@ The returned value of this command is unpredictable.
This function runs @code{byte-compile-file} on files specified on the
command line. This function must be used only in a batch execution of
Emacs, as it kills Emacs on completion. An error in one file does not
prevent processing of subsequent files. (The file which gets the error
prevent processing of subsequent files. (The file that gets the error
will not, of course, produce any compiled code.)
@example
@ -238,12 +238,13 @@ this way.
@end defspec
@defspec eval-when-compile body
This form marks @var{body} to be evaluated at compile time @emph{only}.
The result of evaluation by the compiler becomes a constant which
appears in the compiled program. When the program is interpreted, not
compiled at all, @var{body} is evaluated normally.
This form marks @var{body} to be evaluated at compile time and not when
the compiled program is loaded. The result of evaluation by the
compiler becomes a constant which appears in the compiled program. When
the program is interpreted, not compiled at all, @var{body} is evaluated
normally.
At top-level, this is analogous to the Common Lisp idiom
At top level, this is analogous to the Common Lisp idiom
@code{(eval-when (compile eval) @dots{})}. Elsewhere, the Common Lisp
@samp{#.} reader macro (but not when interpreting) is closer to what
@code{eval-when-compile} does.
@ -279,7 +280,8 @@ The list of argument symbols.
The string containing the byte-code instructions.
@item constants
The vector of constants referenced by the byte code.
The vector of Lisp objects referenced by the byte code. These include
symbols used as function names and variable names.
@item stacksize
The maximum stack size this function needs.
@ -318,7 +320,7 @@ with @var{elements} as its elements.
You should not try to come up with the elements for a byte-code
function yourself, because if they are inconsistent, Emacs may crash
when you call the function. Always leave it to the byte-compiler to
when you call the function. Always leave it to the byte compiler to
create these objects; it makes the elements consistent (we hope).
You can access the elements of a byte-code object using @code{aref};
@ -336,11 +338,11 @@ form.
The byte-code interpreter is implemented as a simple stack machine.
It pushes values onto a stack of its own, then pops them off to use them
in calculations and push the result back on the stack. When a byte-code
function returns, it pops a value off the stack and returns it as the
value of the function.
in calculations whose results are themselves pushed back on the stack.
When a byte-code function returns, it pops a value off the stack and
returns it as the value of the function.
In addition to the stack, byte-code functions can use, bind and set
In addition to the stack, byte-code functions can use, bind, and set
ordinary Lisp variables, by transferring values between variables and
the stack.
@ -442,7 +444,7 @@ they still serve their purpose.
@group
; @r{Stack now contains:}
; @minus{} @r{result of result of recursive}
; @minus{} @r{result of recursive}
; @r{call to @code{factorial}}
; @minus{} @r{value of @code{integer}}
; @minus{} @r{@code{*}}
@ -537,10 +539,10 @@ The @code{silly-loop} function is somewhat more complex:
@end group
@group
9 goto-if-nil-else-pop 17 ; @r{Goto 17 if @code{n} > 0}
9 goto-if-nil-else-pop 17 ; @r{Goto 17 if @code{n} <= 0}
; @r{(this exits the while loop).}
; @r{else pop top of stack}
; @r{and continue}
; @r{(this exits the while loop).}
@end group
@group
@ -563,6 +565,8 @@ The @code{silly-loop} function is somewhat more complex:
@group
17 discard ; @r{Discard result of while loop}
; @r{by popping top of stack.}
; @r{This result is the value @code{nil} that}
; @r{was not popped by the goto at 9.}
@end group
@group

61
lispref/loading.texi
View file

@ -21,8 +21,8 @@ in an Emacs buffer.
@cindex top-level form
The loaded file must contain Lisp expressions, either as source code
or, optionally, as byte-compiled code. Each form in the file is called
a @dfn{top-level form}. There is no special format for the forms in a
or as byte-compiled code. Each form in the file is called a
@dfn{top-level form}. There is no special format for the forms in a
loadable file; any form in a file may equally well be typed directly
into a buffer and evaluated there. (Indeed, most code is tested this
way.) Most often, the forms are function definitions and variable
@ -61,7 +61,7 @@ To find the file, @code{load} first looks for a file named
@file{@var{filename}.elc}, that is, for a file whose name is
@var{filename} with @samp{.elc} appended. If such a file exists, it is
loaded. If there is no file by that name, then @code{load} looks for a
file names @file{@var{filename}.el}. If that file exists, it is loaded.
file named @file{@var{filename}.el}. If that file exists, it is loaded.
Finally, if neither of those names is found, @code{load} looks for a
file named @var{filename} with nothing appended, and loads it if it
exists. (The @code{load} function is not clever about looking at
@ -92,8 +92,8 @@ non-@code{nil}.
@cindex load errors
Any unhandled errors while loading a file terminate loading. If the
load was done for the sake of @code{autoload}, certain kinds of
top-level forms, those which define functions, are undone.
load was done for the sake of @code{autoload}, any function definitions
made during the loading are undone.
@kindex file-error
If @code{load} can't find the file to load, then normally it signals the
@ -166,11 +166,12 @@ followed then by the @file{/user/bil/emacs} directory and then by
the @file{/usr/local/lisplib} directory,
which are then followed by the standard directories for Lisp code.
The command line options @samp{-l} or @samp{-load} specify Lispa library
to load. Since this file might be in the current directory, Emacs 18
temporarily adds the current directory to the front of @code{load-path}
so the file can be found there. Newer Emacs versions also find such
files in the current directory, but without altering @code{load-path}.
The command line options @samp{-l} or @samp{-load} specify a Lisp
library to load as part of Emacs startup. Since this file might be in
the current directory, Emacs 18 temporarily adds the current directory
to the front of @code{load-path} so the file can be found there. Newer
Emacs versions also find such files in the current directory, but
without altering @code{load-path}.
@end defopt
@defvar load-in-progress
@ -202,8 +203,8 @@ for the command @code{update-file-autoloads}, which constructs calls to
comments are the most convenient way to make a function autoload, but
only for packages installed along with Emacs.
@defun autoload symbol filename &optional docstring interactive type
This function defines the function (or macro) named @var{symbol} so as
@defun autoload function filename &optional docstring interactive type
This function defines the function (or macro) named @var{function} so as
to load automatically from @var{filename}. The string @var{filename}
specifies the file to load to get the real definition of @var{function}.
@ -227,9 +228,9 @@ keymap. Various parts of Emacs need to know this information without
loading the real definition.
@cindex function cell in autoload
If @var{symbol} already has a non-void function definition that is not
If @var{function} already has a non-void function definition that is not
an autoload object, @code{autoload} does nothing and returns @code{nil}.
If the function cell of @var{symbol} is void, or is already an autoload
If the function cell of @var{function} is void, or is already an autoload
object, then it is defined as an autoload object like this:
@example
@ -278,11 +279,11 @@ autoloads for all files in the current directory.
The same magic comment can copy any kind of form into
@file{loaddefs.el}. If the form following the magic comment is not a
function definition, it is copied verbatim. You can also use a magic
comment to execute a form at build time executing it when the file
itself is loaded. To do this, write the form @dfn{on the same line} as
the magic comment. Since it is in a comment, it does nothing when you
load the source file; but @code{update-file-autoloads} copies it to
@file{loaddefs.el}, where it is executed while building Emacs.
comment to execute a form at build time @emph{without} executing it when
the file itself is loaded. To do this, write the form @dfn{on the same
line} as the magic comment. Since it is in a comment, it does nothing
when you load the source file; but @code{update-file-autoloads} copies
it to @file{loaddefs.el}, where it is executed while building Emacs.
The following example shows how @code{doctor} is prepared for
autoloading with a magic comment:
@ -367,7 +368,9 @@ has been loaded before:
@noindent
If the library uses @code{provide} to provide a named feature, you can
use @code{featurep} to test whether the library has been loaded.
@ifinfo
@xref{Features}.
@end ifinfo
@node Features
@section Features
@ -391,7 +394,7 @@ hasn't been loaded already.
feature name as argument. @code{require} looks in the global variable
@code{features} to see whether the desired feature has been provided
already. If not, it loads the feature from the appropriate file. This
file should call @code{provide} at the top-level to add the feature to
file should call @code{provide} at the top level to add the feature to
@code{features}; if it fails to do so, @code{require} signals an error.
@cindex load error with require
@ -427,7 +430,7 @@ This adds @code{comint} to the global @code{features} list, so that
done.
@cindex byte-compiling @code{require}
When @code{require} is used at top-level in a file, it takes effect
When @code{require} is used at top level in a file, it takes effect
when you byte-compile that file (@pxref{Byte Compilation}) as well as
when you load it. This is in case the required package contains macros
that the byte compiler must know about.
@ -446,6 +449,12 @@ feature, as in the following example.
@end group
@end smallexample
@noindent
The compiler ignores the @code{provide}, then processes the
@code{require} by loading the file in question. Loading the file does
execute the @code{provide} call, so the subsequent @code{require} call
does nothing while loading.
@defun provide feature
This function announces that @var{feature} is now loaded, or being
loaded, into the current Emacs session. This means that the facilities
@ -508,10 +517,10 @@ reclaim memory for other Lisp objects. To do this, use the function
@deffn Command unload-feature feature
This command unloads the library that provided feature @var{feature}.
It undefines all functions and variables defined with @code{defvar},
@code{defmacro}, @code{defconst}, @code{defsubst} and @code{defalias} by
that library. It then restores any autoloads associated with those
symbols.
It undefines all functions, macros, and variables defined in that
library with @code{defconst}, @code{defvar}, @code{defun},
@code{defmacro}, @code{defsubst} and @code{defalias}. It then restores
any autoloads formerly associated with those symbols.
@end deffn
The @code{unload-feature} function is written in Lisp; its actions are
@ -528,7 +537,7 @@ composed of these kinds of objects:
@itemize @bullet
@item
Symbols, which were defined as functions or variables.
Symbols that were defined by this library.
@item
Lists of the form @code{(require . @var{feature})} indicating
features that were required.