@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1994, 2001-2014 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1994, 2001-2016 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Byte Compilation
@chapter Byte Compilation
If @var{symbol}'s definition is a byte-code function object,
@code{byte-compile} does nothing and returns @code{nil}. It does not
-``compile the symbol's definition again'', since the original
+compile the symbol's definition again, since the original
(non-compiled) code has already been replaced in the symbol's function
cell by the byte-compiled code.
When Emacs loads functions and variables from a byte-compiled file,
it normally does not load their documentation strings into memory.
-Each documentation string is ``dynamically'' loaded from the
+Each documentation string is dynamically loaded from the
byte-compiled file only when needed. This saves memory, and speeds up
loading by skipping the processing of the documentation strings.
accomplished by writing compiled files with a special Lisp reader
construct, @samp{#@@@var{count}}. This construct skips the next
@var{count} characters. It also uses the @samp{#$} construct, which
-stands for ``the name of this file, as a string''. Do not use these
+stands for the name of this file, as a string. Do not use these
constructs in Lisp source files; they are not designed to be clear to
humans reading the file.
@node Eval During Compile
@section Evaluation During Compilation
+@cindex eval during compilation
These features permit you to write code to be evaluated during
compilation of a program.
@section Compiler Errors
@cindex compiler errors
- Byte compilation outputs all errors and warnings into the buffer
-@file{*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
+ Error and warning messages from byte compilation are printed in a
+buffer named @file{*Compile-Log*}. These messages include file names
+and line numbers identifying the location of the problem. The usual
+Emacs commands for operating on compiler output can be used on these
messages.
When an error is due to invalid syntax in the program, the byte
compiler might get confused about the errors' exact location. One way
-to investigate is to switch to the buffer @w{@file{ *Compiler Input*}}.
-(This buffer name starts with a space, so it does not show up in
-@kbd{M-x list-buffers}.) This buffer contains the program being
+to investigate is to switch to the buffer @w{@file{ *Compiler
+Input*}}. (This buffer name starts with a space, so it does not show
+up in the Buffer Menu.) This buffer contains the program being
compiled, and point shows how far the byte compiler was able to read;
the cause of the error might be nearby. @xref{Syntax Errors}, for
some tips for locating syntax errors.
- When the byte compiler warns about functions that were used but not
-defined, it always reports the line number for the end of the file,
-not the locations where the missing functions were called. To find
-the latter, you must search for the function names.
+ A common type of warning issued by the byte compiler is for
+functions and variables that were used but not defined. Such warnings
+report the line number for the end of the file, not the locations
+where the missing functions or variables were used; to find these, you
+must search the file manually.
- 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:
+ If you are sure that a warning message about a missing function or
+variable is unjustified, there are several ways to suppress it:
+
+@itemize @bullet
+@item
+You can suppress the warning for a specific call to a function
+@var{func} by conditionalizing it on an @code{fboundp} test, like
+this:
@example
(if (fboundp '@var{func}) ...(@var{func} ...)...)
@code{if}, and @var{func} must appear quoted in the call to
@code{fboundp}. (This feature operates for @code{cond} as well.)
- You can tell the compiler that a function is defined using
-@code{declare-function} (@pxref{Declaring Functions}). Likewise, you
-can tell the compiler that a variable is defined using @code{defvar}
-with no initial value.
-
- You can suppress the compiler warning for a specific use of an
-undefined variable @var{variable} by conditionalizing its use on a
-@code{boundp} test, like this:
+@item
+Likewise, you can suppress the warning for a specific use of a
+variable @var{variable} by conditionalizing it on a @code{boundp}
+test:
@example
(if (boundp '@var{variable}) ...@var{variable}...)
@code{if}, and @var{variable} must appear quoted in the call to
@code{boundp}.
- You can suppress any and all compiler warnings within a certain
+@item
+You can tell the compiler that a function is defined using
+@code{declare-function}. @xref{Declaring Functions}.
+
+@item
+Likewise, you can tell the compiler that a variable is defined using
+@code{defvar} with no initial value. (Note that this marks the
+variable as special.) @xref{Defining Variables}.
+@end itemize
+
+ You can also suppress any and all compiler warnings within a certain
expression using the construct @code{with-no-warnings}:
@c This is implemented with a defun, but conceptually it is
one you intend to suppress.
@end defspec
- More precise control of warnings is possible by setting the variable
-@code{byte-compile-warnings}.
+ Byte compiler warnings can be controlled more precisely by setting
+the variable @code{byte-compile-warnings}. See its documentation
+string for details.
@node Byte-Code Objects
@section Byte-Code Function Objects
normal use. They are:
@table @var
-@item arglist
-The list of argument symbols.
+@item argdesc
+The descriptor of the arguments. This can either be a list of
+arguments, as described in @ref{Argument List}, or an integer encoding
+the required number of arguments. In the latter case, the value of
+the descriptor specifies the minimum number of arguments in the bits
+zero to 6, and the maximum number of arguments in bits 8 to 14. If
+the argument list uses @code{&rest}, then bit 7 is set; otherwise it's
+cleared.
+
+If @var{argdesc} is a list, the arguments will be dynamically bound
+before executing the byte code. If @var{argdesc} is an integer, the
+arguments will be instead pushed onto the stack of the byte-code
+interpreter, before executing the code.
@item byte-code
The string containing the byte-code instructions.
@code{backward-sexp}.
@example
-#[(&optional arg)
- "^H\204^F^@@\301^P\302^H[!\207"
- [arg 1 forward-sexp]
- 2
- 254435
+#[256
+ "\211\204^G^@@\300\262^A\301^A[!\207"
+ [1 forward-sexp]
+ 3
+ 1793299
"^p"]
@end example