# HG changeset patch # User Luc Teirlinck # Date 1074121107 0 # Node ID aaa866b1592f93b13e19d931a6ba4df68bdc8b4f # Parent b5ae5c44ad200cc0c449e9ca2a7a85a0b58bac29 (Compilation Functions): Expand descriptions of `compile-defun', `byte-compile-file', `byte-recompile-directory' and `batch-byte-compile'. In particular, mention and describe all optional arguments. (Disassembly): Correct and clarify the description of `disassemble'. diff -r b5ae5c44ad20 -r aaa866b1592f lispref/compile.texi --- a/lispref/compile.texi Wed Jan 14 22:52:15 2004 +0000 +++ b/lispref/compile.texi Wed Jan 14 22:58:27 2004 +0000 @@ -173,14 +173,18 @@ certain primitives that are coded as special instructions. @end defun -@deffn Command compile-defun +@deffn Command compile-defun &optional arg This command reads the defun containing point, compiles it, and evaluates the result. If you use this on a defun that is actually a function definition, the effect is to install a compiled version of that function. + +@code{compile-defun} normally displays the result of evaluation in the +echo area, but if @var{arg} is non-@code{nil}, it inserts the result +in the current buffer after the form it compiled. @end deffn -@deffn Command byte-compile-file filename +@deffn Command byte-compile-file filename &optional load This function compiles a file of Lisp code named @var{filename} into a file of byte-code. The output file's name is made by changing the @samp{.el} suffix into @samp{.elc}; if @var{filename} does not end in @@ -193,8 +197,11 @@ executed when the file is read. All comments are discarded when the input file is read. -This command returns @code{t}. When called interactively, it prompts -for the file name. +This command returns @code{t} if there were no errors and @code{nil} +otherwise. When called interactively, it prompts for the file name. + +If @var{load} is non-@code{nil}, this command loads the compiled file +after compiling it. Interactively, @var{load} is the prefix argument. @example @group @@ -215,20 +222,28 @@ @end example @end deffn -@deffn Command byte-recompile-directory directory flag +@deffn Command byte-recompile-directory directory &optional flag force @cindex library compilation -This function recompiles every @samp{.el} file in @var{directory} that -needs recompilation. A file needs recompilation if a @samp{.elc} file -exists but is older than the @samp{.el} file. +This command recompiles every @samp{.el} file in @var{directory} (or +its subdirectories) that needs recompilation. A file needs +recompilation if a @samp{.elc} file exists but is older than the +@samp{.el} file. -When a @samp{.el} file has no corresponding @samp{.elc} file, @var{flag} -says what to do. If it is @code{nil}, these files are ignored. If it -is non-@code{nil}, the user is asked whether to compile each such file. +When a @samp{.el} file has no corresponding @samp{.elc} file, +@var{flag} says what to do. If it is @code{nil}, this command ignores +these files. If @var{flag} is 0, it compiles them. If it is neither +@code{nil} nor 0, it asks the user whether to compile each such file. -The returned value of this command is unpredictable. +Interactively, @code{byte-recompile-directory} prompts for +@var{directory} and @var{flag} is the prefix argument. + +If @var{force} is non-@code{nil}, this command recompiles every +@samp{.el} file that has a @samp{.elc} file. + +The returned value is unpredictable. @end deffn -@defun batch-byte-compile +@defun batch-byte-compile &optional noforce 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 @@ -236,6 +251,9 @@ generated for it, and the Emacs process will terminate with a nonzero status code. +If @var{noforce} is non-@code{nil}, this function does not recompile +files that have an up-to-date @samp{.elc} file. + @example % emacs -batch -f batch-byte-compile *.el @end example @@ -420,7 +438,7 @@ defined are always ``located'' at the end of the file, so these commands won't find the places they are really used. To do that, you must search for the function names. - + You can suppress the compiler warning for calling an undefined function @var{func} by conditionalizing the function call on a @code{fboundp} test, like this: @@ -549,14 +567,16 @@ ordinary Lisp variables, by transferring values between variables and the stack. -@deffn Command disassemble object &optional stream -This function prints the disassembled code for @var{object}. If -@var{stream} is supplied, then output goes there. Otherwise, the -disassembled code is printed to the stream @code{standard-output}. The -argument @var{object} can be a function name or a lambda expression. +@deffn Command disassemble object &optional buffer-or-name +This command displays the disassembled code for @var{object}. In +interactive use, or if @var{buffer-or-name} is @code{nil} or omitted, +the output goes in a buffer named @samp{*Disassemble*}. If +@var{buffer-or-name} is non-@code{nil}, it must be a buffer or the +name of an existing buffer. Then the output goes there, at point, and +point is left before the output. -As a special exception, if this function is used interactively, -it outputs to a buffer named @samp{*Disassemble*}. +The argument @var{object} can be a function name, a lambda expression +or a byte-code object. @end deffn Here are two examples of using the @code{disassemble} function. We