* Eval During Compile:: Code to be evaluated when you compile.
* Compiled-Function Objects:: The data type used for byte-compiled functions.
* Disassembly:: Disassembling byte-code; how to read byte-code.
+* Different Behavior:: When compiled code gives different results.
@end menu
@node Speed of Byte-Code
@end deffn
@c flag is not optional in FSF Emacs
-@deffn Command byte-recompile-directory directory &optional flag
+@deffn Command byte-recompile-directory directory &optional flag norecursion 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.
+Files in subdirectories of @var{directory} are also processed unless
+optional argument @var{norecursion} is non-@code{nil}.
+
When a @samp{.el} file has no corresponding @samp{.elc} file, then
@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 the fourth optional argument @var{force} is non-@code{nil},
+recompile every @samp{.el} file that already has a @samp{.elc} file.
+
The return value of this command is unpredictable.
@end deffn
@code{batch-byte-recompile-directory}.
@end defvar
-@defun byte-code instructions constants stack-size
+@defun byte-code instructions constants stack-depth
@cindex byte-code interpreter
This function actually interprets byte-code.
Don't call this function yourself. Only the byte compiler knows how to
The vector of Lisp objects referenced by the byte code. These include
symbols used as function names and variable names.
-@item stack-size
+@item stack-depth
The maximum stack size this function needs.
@item doc-string
The primitive way to create a compiled-function object is with
@code{make-byte-code}:
-@defun make-byte-code arglist instructions constants stack-size &optional doc-string interactive
+@defun make-byte-code arglist instructions constants stack-depth &optional doc-string interactive
This function constructs and returns a compiled-function object
with the specified attributes.
compiled-function object @var{function}.
@end defun
-@defun compiled-function-stack-size function
+@defun compiled-function-stack-depth function
This function returns the maximum stack size needed by compiled-function
object @var{function}.
@end defun
@end example
+@node Different Behavior
+@section Different Behavior
+
+The intent is that compiled byte-code and the corresponding code
+executed by the Lisp interpreter produce identical results. However,
+there are some circumstances where the results will differ.
+
+@itemize @bullet
+@item
+Arithmetic operations may be rearranged for efficiency or compile-time
+evaluation. When floating point numbers are involved, this may produce
+different values or an overflow.
+@item
+Some arithmetic operations may be optimized away. For example, the
+expression @code{(+ x)} may be optimized to simply @code{x}. If the
+value of @code{x} is a marker, then the value will be a marker instead
+of an integer. If the value of @samp{x} is a cons cell, then the
+interpreter will issue an error, while the bytecode will not.
+
+If you're trying to use @samp{(+ @var{object} 0)} to convert
+@var{object} to integer, consider using an explicit conversion function,
+which is clearer and guaranteed to work.
+Instead of @samp{(+ @var{marker} 0)}, use @samp{(marker-position @var{marker})}.
+Instead of @samp{(+ @var{char} 0)}, use @samp{(char-int @var{char})}.
+@end itemize
+
+For maximal equivalence between interpreted and compiled code, the
+variables @code{byte-compile-delete-errors} and
+@code{byte-compile-optimize} can be set to @code{nil}, but this is not
+recommended.