operand of an instruction. The vector contains all the constants,
variable names and function names used by the function, except for
certain primitives that are coded as special instructions.
+
+If the argument to @code{byte-compile} is a @code{lambda} expression,
+it returns the corresponding compiled code, but does not store
+it anywhere.
@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
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
@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}, 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,
+and asks about each subdirectory as well.
-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.
+Interactively, @code{byte-recompile-directory} prompts for
+@var{directory} and @var{flag} is the prefix argument.
-The returned value of this command is unpredictable.
+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
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
@item
If you alter the compiled file (such as by compiling a new version),
-then further access to documentation strings in this file will give
-nonsense results.
+then further access to documentation strings in this file will
+probably give nonsense results.
@end itemize
If your site installs Emacs following the usual procedures, these
@item
If you alter the compiled file (such as by compiling a new version),
-then trying to load any function not already loaded will yield nonsense
-results.
+then trying to load any function not already loaded will usually yield
+nonsense results.
@end itemize
These problems will never happen in normal circumstances with
@end defvar
@defun fetch-bytecode function
-This immediately finishes loading the definition of @var{function} from
-its byte-compiled file, if it is not fully loaded already. The argument
-@var{function} may be a byte-code function object or a function name.
+If @var{function} is a byte-code function object, this immediately
+finishes loading the byte code of @var{function} from its
+byte-compiled file, if it is not fully loaded already. Otherwise,
+it does nothing. It always returns @var{function}.
@end defun
@node Eval During Compile
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
+function @var{func} by conditionalizing the function call on an
@code{fboundp} test, like this:
@example
@end example
@noindent
-The call to @var{func} must be in the @var{then-form} of the @code{if},
-and @var{func} must appear quoted in the call to @code{fboundp}.
-Likewise, you can suppress a compiler warning for an unbound variable
+The call to @var{func} must be in the @var{then-form} of the
+@code{if}, and @var{func} must appear quoted in the call to
+@code{fboundp}. (This feature operates for @code{cond} as well.)
+
+ Likewise, you can suppress a compiler warning for an unbound variable
@var{variable} by conditionalizing its use on a @code{boundp} test,
like this:
You can suppress any compiler warnings using the construct
@code{with-no-warnings}:
-@defmac with-no-warnings body...
+@c This is implemented with a defun, but conceptually it is
+@c a special form.
+
+@defspec with-no-warnings body...
In execution, this is equivalent to @code{(progn @var{body}...)},
but the compiler does not issue warnings for anything that occurs
inside @var{body}.
We recommend that you use this construct around the smallest
possible piece of code.
-@end defmac
+@end defspec
@node Byte-Code Objects
@section Byte-Code Function Objects
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.
-
-As a special exception, if this function is used interactively,
-it outputs to a buffer named @samp{*Disassemble*}.
+@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.
+
+The argument @var{object} can be a function name, a lambda expression
+or a byte-code object. If it is a lambda expression, @code{disassemble}
+compiles it and disassembles the resulting compiled code.
@end deffn
Here are two examples of using the @code{disassemble} function. We
HCoop / bpt / emacs.git / blobdiff