Mercurial > emacs
changeset 7212:2f1305fcecf6
entered into RCS
| author | Richard M. Stallman <rms@gnu.org> |
|---|---|
| date | Sat, 30 Apr 1994 01:38:51 +0000 |
| parents | b2485e94101a |
| children | bb5db306a305 |
| files | lispref/compile.texi lispref/loading.texi |
| diffstat | 2 files changed, 58 insertions(+), 45 deletions(-) [+] |
line wrap: on
line diff
--- a/lispref/compile.texi Sat Apr 30 00:51:52 1994 +0000 +++ b/lispref/compile.texi Sat Apr 30 01:38:51 1994 +0000 @@ -86,9 +86,9 @@ @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 @@ 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 @@ 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 @@ @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 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 @@ 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 @@ 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 @@ @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 @@ @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 @@ @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
--- a/lispref/loading.texi Sat Apr 30 00:51:52 1994 +0000 +++ b/lispref/loading.texi Sat Apr 30 01:38:51 1994 +0000 @@ -21,8 +21,8 @@ @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 @@ @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 @@ @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 @@ 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 @@ 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 @@ 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 @@ 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 @@ @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 @@ 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 @@ 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 @@ @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 @@ @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 @@ @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.