not work in subsequent versions if they contain character constants with
modifier bits.
+@vindex no-byte-compile
+ If you do not want a Lisp file to be compiled, ever, put a file-local
+variable binding for @code{no-byte-compile} into it, like this:
+
+@example
+;; -*-no-byte-compile: t; -*-
+@end example
+
@xref{Compilation Errors}, for how to investigate errors occurring in
byte compilation.
* Docs and Compilation:: Dynamic loading of documentation strings.
* Dynamic Loading:: Dynamic loading of individual functions.
* Eval During Compile:: Code to be evaluated when you compile.
+* Compiler Errors:: Handling compiler error messages.
* Byte-Code Objects:: The data type used for byte-compiled functions.
* Disassembly:: Disassembling byte-code; how to read byte-code.
@end menu
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.
+
+Interactively, @code{byte-recompile-directory} prompts for
+@var{directory} and @var{flag} is the prefix argument.
-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.
+If @var{force} is non-@code{nil}, this command recompiles every
+@samp{.el} file that has a @samp{.elc} file.
-The returned value of this command is unpredictable.
+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
to what @code{eval-when-compile} does.
@end defspec
+@node Compiler Errors
+@section Compiler Errors
+@cindex compiler errors
+
+ Byte compilation writes errors and warnings into the buffer
+@samp{*Compile-Log*}. The messages include file names and line
+numbers that identify the location of the problem. The usual Emacs
+commands for operating on compiler diagnostics work properly on
+these messages.
+
+ However, the warnings about functions that were used but not
+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 an
+@code{fboundp} test, like this:
+
+@example
+(if (fboundp '@var{func}) ...(@var{func} ...)...)
+@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}. (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:
+
+@example
+(if (boundp '@var{variable}) ...@var{variable}...)
+@end example
+
+@noindent
+The reference to @var{variable} must be in the @var{then-form} of the
+@code{if}, and @var{variable} must appear quoted in the call to
+@code{boundp}.
+
+ You can suppress any compiler warnings using the construct
+@code{with-no-warnings}:
+
+@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 defspec
+
@node Byte-Code Objects
@section Byte-Code Function Objects
@cindex compiled function
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
@end example
+@ignore
+ arch-tag: f78e3050-2f0a-4dee-be27-d9979a0a2289
+@end ignore
HCoop / bpt / emacs.git / blobdiff