@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/compile
-@node Byte Compilation, Debugging, Loading, Top
+@node Byte Compilation, Advising Functions, Loading, Top
@chapter Byte Compilation
@cindex byte-code
@cindex compilation
- GNU Emacs Lisp has a @dfn{compiler} that translates functions written
+ Emacs Lisp has a @dfn{compiler} that translates functions written
in Lisp into a special representation called @dfn{byte-code} that can be
executed more efficiently. The compiler replaces Lisp function
definitions with byte-code. When a byte-code function is called, its
transportable from machine to machine without recompilation. It is not,
however, as fast as true compiled code.
+ Compiling a Lisp file with the Emacs byte compiler always reads the
+file as multibyte text, even if Emacs was started with @samp{--unibyte},
+unless the file specifies otherwise. This is so that compilation gives
+results compatible with running the same file without compilation.
+@xref{Loading Non-ASCII}.
+
In general, any version of Emacs can run byte-compiled code produced
-by recent earlier versions of Emacs, but the reverse is not true. In
-particular, if you compile a program with Emacs 19.29, the compiled
-code does not run in earlier versions.
+by recent earlier versions of Emacs, but the reverse is not true. A
+major incompatible change was introduced in Emacs version 19.29, and
+files compiled with versions since that one will definitely not run
+in earlier versions unless you specify a special option.
@iftex
@xref{Docs and Compilation}.
@end iftex
-Files compiled in versions before 19.29 may not work in 19.29 if they
-contain character constants with modifier bits, because the bits were
-renumbered in Emacs 19.29.
+In addition, the modifier bits in keyboard characters were renumbered in
+Emacs 19.29; as a result, files compiled in versions before 19.29 will
+not work in subsequent versions if they contain character constants with
+modifier bits.
@xref{Compilation Errors}, for how to investigate errors occurring in
byte compilation.
@code{byte-compile-file}, or several files with
@code{byte-recompile-directory} or @code{batch-byte-compile}.
- When you run the byte compiler, you may get warnings in a buffer
-called @samp{*Compile-Log*}. These report things in your program that
-suggest a problem but are not necessarily erroneous.
+ The byte compiler produces error messages and warnings about each file
+in a buffer called @samp{*Compile-Log*}. These report things in your
+program that suggest a problem but are not necessarily erroneous.
@cindex macro compilation
- Be careful when byte-compiling code that uses macros. Macro calls are
-expanded when they are compiled, so the macros must already be defined
-for proper compilation. For more details, see @ref{Compiling Macros}.
+ Be careful when writing macro calls in files that you may someday
+byte-compile. Macro calls are expanded when they are compiled, so the
+macros must already be defined for proper compilation. For more
+details, see @ref{Compiling Macros}.
Normally, compiling a file does not evaluate the file's contents or
load the file. But it does execute any @code{require} calls at top
@end deffn
@deffn Command byte-compile-file filename
-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 appending
-@samp{c} to the end of @var{filename}.
+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
+@samp{.el}, it adds @samp{.elc} to the end of @var{filename}.
Compilation works by reading the input file one form at a time. If it
is a definition of a function or macro, the compiled function or macro
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, 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.
+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.
The returned value of this command is unpredictable.
@end deffn
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
-prevent processing of subsequent files. (The file that gets the error
-will not, of course, produce any compiled code.)
+prevent processing of subsequent files, but no output file will be
+generated for it, and the Emacs process will terminate with a nonzero
+status code.
@example
% emacs -batch -f batch-byte-compile *.el
@cindex byte-code interpreter
This function actually interprets byte-code. A byte-compiled function
is actually defined with a body that calls @code{byte-code}. Don't call
-this function yourself. Only the byte compiler knows how to generate
+this function yourself---only the byte compiler knows how to generate
valid calls to this function.
-In newer Emacs versions (19 and up), byte-code is usually executed as
-part of a byte-code function object, and only rarely due to an explicit
-call to @code{byte-code}.
+In Emacs version 18, byte-code was always executed by way of a call to
+the function @code{byte-code}. Nowadays, byte-code is usually executed
+as part of a byte-code function object, and only rarely through an
+explicit call to @code{byte-code}.
@end defun
@node Docs and Compilation
Functions and variables loaded from a byte-compiled file access their
documentation strings dynamically from the file whenever needed. This
-saves space within Emacs, and make loading faster because the
+saves space within Emacs, and makes loading faster because the
documentation strings themselves need not be processed while loading the
file. Actual access to the documentation strings becomes slower as a
result, but this normally is not enough to bother users.
installed, its files will remain unmodified in the places where they are
expected to be.
- However, if you have build Emacs yourself and use it from the
+ However, if you have built Emacs yourself and use it from the
directory where you built it, you will experience this problem
occasionally if you edit and recompile Lisp files. When it happens, you
can cure the problem by reloading the file after recompiling it.
- Byte-compiled files made with Emacs 19.29 will not load into older
-versions because the older versions don't support this feature. You can
-turn off this feature by setting @code{byte-compile-dynamic-docstrings}
-to @code{nil}. Once this is done, you can compile files that will load
-into older Emacs versions. You can do this globally, or for one source
-file by specifying a file-local binding for the variable. Here's one
-way to do that:
+ Byte-compiled files made with recent versions of Emacs (since 19.29)
+will not load into older versions because the older versions don't
+support this feature. You can turn off this feature at compile time by
+setting @code{byte-compile-dynamic-docstrings} to @code{nil}; then you
+can compile files that will load into older Emacs versions. You can do
+this globally, or for one source file by specifying a file-local binding
+for the variable. One way to do that is by adding this string to the
+file's first line:
@example
-*-byte-compile-dynamic-docstrings: nil;-*-
use 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.'' It is best not to use these constructs in Lisp source files.
+string.'' It is usually best not to use these constructs in Lisp source
+files, since they are not designed to be clear to humans reading the
+file.
@node Dynamic Loading
@section Dynamic Loading of Individual Functions
The advantage of dynamic function loading is that loading the file
becomes much faster. This is a good thing for a file which contains
-many separate commands, provided that using one of them does not imply
-you will soon (or ever) use the rest. A specialized mode which provides
-many keyboard commands often has that usage pattern: a user may invoke
-the mode, but use only a few of the commands it provides.
+many separate user-callable functions, if using one of them does not
+imply you will probably also use the rest. A specialized mode which
+provides many keyboard commands often has that usage pattern: a user may
+invoke the mode, but use only a few of the commands it provides.
The dynamic loading feature has certain disadvantages:
@item
If you alter the compiled file (such as by compiling a new version),
-then trying to load any function not already loaded will get nonsense
+then trying to load any function not already loaded will yield nonsense
results.
@end itemize
- If you compile a new version of the file, the best thing to do is
-immediately load the new compiled file. That will prevent any future
-problems.
+ These problems will never happen in normal circumstances with
+installed Emacs files. But they are quite likely to happen with Lisp
+files that you are changing. The easiest way to prevent these problems
+is to reload the new compiled file immediately after each recompilation.
The byte compiler uses the dynamic function loading feature if the
variable @code{byte-compile-dynamic} is non-@code{nil} at compilation
time. Do not set this variable globally, since dynamic loading is
desirable only for certain files. Instead, enable the feature for
-specific source files with file-local variable bindings, like this:
+specific source files with file-local variable bindings. For example,
+you could do it by writing this text in the source file's first line:
@example
-*-byte-compile-dynamic: t;-*-
containing code and when you run it (whether compiled or not).
You can get a similar result by putting @var{body} in a separate file
-and referring to that file with @code{require}. Using @code{require} is
-preferable if there is a substantial amount of code to be executed in
-this way.
+and referring to that file with @code{require}. That method is
+preferable when @var{body} is large.
@end defspec
@defspec eval-when-compile body
-This form marks @var{body} to be evaluated at compile time and not when
+This form marks @var{body} to be evaluated at compile time but not when
the compiled program is loaded. The result of evaluation by the
-compiler becomes a constant which appears in the compiled program. When
-the program is interpreted, not compiled at all, @var{body} is evaluated
-normally.
-
-At top level, this is analogous to the Common Lisp idiom
-@code{(eval-when (compile eval) @dots{})}. Elsewhere, the Common Lisp
-@samp{#.} reader macro (but not when interpreting) is closer to what
-@code{eval-when-compile} does.
+compiler becomes a constant which appears in the compiled program. If
+you load the source file, rather than compiling it, @var{body} is
+evaluated normally.
+
+@strong{Common Lisp Note:} At top level, this is analogous to the Common
+Lisp idiom @code{(eval-when (compile eval) @dots{})}. Elsewhere, the
+Common Lisp @samp{#.} reader macro (but not when interpreting) is closer
+to what @code{eval-when-compile} does.
@end defspec
@node Byte-Code Objects
function object is like that for a vector, with an additional @samp{#}
before the opening @samp{[}.
- In Emacs version 18, there was no byte-code function object data type;
-compiled functions used the function @code{byte-code} to run the byte
-code.
-
A byte-code function object must have at least four elements; there is
-no maximum number, but only the first six elements are actually used.
+no maximum number, but only the first six elements have any normal use.
They are:
@table @var
HCoop / bpt / emacs.git / blobdiff