XEmacs 21.4.10 "Military Intelligence".
[chise/xemacs-chise.git] / man / lispref / compile.texi
1 @c -*-texinfo-*-
2 @c This is part of the XEmacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c See the file lispref.texi for copying conditions.
5 @setfilename ../../info/compile.info
6 @node Byte Compilation, Debugging, Loading, Top
7 @chapter Byte Compilation
8 @cindex byte-code
9 @cindex compilation
10
11   XEmacs Lisp has a @dfn{compiler} that translates functions written
12 in Lisp into a special representation called @dfn{byte-code} that can be
13 executed more efficiently.  The compiler replaces Lisp function
14 definitions with byte-code.  When a byte-coded function is called, its
15 definition is evaluated by the @dfn{byte-code interpreter}.
16
17   Because the byte-compiled code is evaluated by the byte-code
18 interpreter, instead of being executed directly by the machine's
19 hardware (as true compiled code is), byte-code is completely
20 transportable from machine to machine without recompilation.  It is not,
21 however, as fast as true compiled code.
22
23 In general, any version of Emacs can run byte-compiled code produced
24 by recent earlier versions of Emacs, but the reverse is not true.  In
25 particular, if you compile a program with XEmacs 20, the compiled code
26 may not run in earlier versions.
27
28 The first time a compiled-function object is executed, the byte-code
29 instructions are validated and the byte-code is further optimized.  An
30 @code{invalid-byte-code} error is signaled if the byte-code is invalid,
31 for example if it contains invalid opcodes.  This usually means a bug in
32 the byte compiler.
33
34 @iftex
35 @xref{Docs and Compilation}.
36 @end iftex
37
38   @xref{Compilation Errors}, for how to investigate errors occurring in
39 byte compilation.
40
41 @menu
42 * Speed of Byte-Code::          An example of speedup from byte compilation.
43 * Compilation Functions::       Byte compilation functions.
44 * Compilation Options::         Controlling the byte compiler's behavior.
45 * Docs and Compilation::        Dynamic loading of documentation strings.
46 * Dynamic Loading::             Dynamic loading of individual functions.
47 * Eval During Compile::         Code to be evaluated when you compile.
48 * Compiled-Function Objects::   The data type used for byte-compiled functions.
49 * Disassembly::                 Disassembling byte-code; how to read byte-code.
50 * Different Behavior::          When compiled code gives different results.
51 @end menu
52
53 @node Speed of Byte-Code
54 @section Performance of Byte-Compiled Code
55
56   A byte-compiled function is not as efficient as a primitive function
57 written in C, but runs much faster than the version written in Lisp.
58 Here is an example:
59
60 @example
61 @group
62 (defun silly-loop (n)
63   "Return time before and after N iterations of a loop."
64   (let ((t1 (current-time-string)))
65     (while (> (setq n (1- n))
66               0))
67     (list t1 (current-time-string))))
68 @result{} silly-loop
69 @end group
70
71 @group
72 (silly-loop 5000000)
73 @result{} ("Mon Sep 14 15:51:49 1998"
74     "Mon Sep 14 15:52:07 1998")  ; @r{18 seconds}
75 @end group
76
77 @group
78 (byte-compile 'silly-loop)
79 @result{} #<compiled-function
80 (n)
81 "...(23)"
82 [current-time-string t1 n 0]
83 2
84 "Return time before and after N iterations of a loop.">
85 @end group
86
87 @group
88 (silly-loop 5000000)
89 @result{} ("Mon Sep 14 15:53:43 1998"
90     "Mon Sep 14 15:53:49 1998")  ; @r{6 seconds}
91 @end group
92 @end example
93
94   In this example, the interpreted code required 18 seconds to run,
95 whereas the byte-compiled code required 6 seconds.  These results are
96 representative, but actual results will vary greatly.
97
98 @node Compilation Functions
99 @comment  node-name,  next,  previous,  up
100 @section The Compilation Functions
101 @cindex compilation functions
102
103   You can byte-compile an individual function or macro definition with
104 the @code{byte-compile} function.  You can compile a whole file with
105 @code{byte-compile-file}, or several files with
106 @code{byte-recompile-directory} or @code{batch-byte-compile}.
107
108   When you run the byte compiler, you may get warnings in a buffer
109 called @samp{*Compile-Log*}.  These report things in your program that
110 suggest a problem but are not necessarily erroneous.
111
112 @cindex macro compilation
113   Be careful when byte-compiling code that uses macros.  Macro calls are
114 expanded when they are compiled, so the macros must already be defined
115 for proper compilation.  For more details, see @ref{Compiling Macros}.
116
117   Normally, compiling a file does not evaluate the file's contents or
118 load the file.  But it does execute any @code{require} calls at top
119 level in the file.  One way to ensure that necessary macro definitions
120 are available during compilation is to @code{require} the file that defines
121 them (@pxref{Named Features}).  To avoid loading the macro definition files
122 when someone @emph{runs} the compiled program, write
123 @code{eval-when-compile} around the @code{require} calls (@pxref{Eval
124 During Compile}).
125
126 @defun byte-compile symbol
127 This function byte-compiles the function definition of @var{symbol},
128 replacing the previous definition with the compiled one.  The function
129 definition of @var{symbol} must be the actual code for the function;
130 i.e., the compiler does not follow indirection to another symbol.
131 @code{byte-compile} returns the new, compiled definition of
132 @var{symbol}.
133
134   If @var{symbol}'s definition is a compiled-function object,
135 @code{byte-compile} does nothing and returns @code{nil}.  Lisp records
136 only one function definition for any symbol, and if that is already
137 compiled, non-compiled code is not available anywhere.  So there is no
138 way to ``compile the same definition again.''
139
140 @example
141 @group
142 (defun factorial (integer)
143   "Compute factorial of INTEGER."
144   (if (= 1 integer) 1
145     (* integer (factorial (1- integer)))))
146 @result{} factorial
147 @end group
148
149 @group
150 (byte-compile 'factorial)
151 @result{} #<compiled-function
152 (integer)
153 "...(21)"
154 [integer 1 factorial]
155 3
156 "Compute factorial of INTEGER.">
157 @end group
158 @end example
159
160 @noindent
161 The result is a compiled-function object.  The string it contains is
162 the actual byte-code; each character in it is an instruction or an
163 operand of an instruction.  The vector contains all the constants,
164 variable names and function names used by the function, except for
165 certain primitives that are coded as special instructions.
166 @end defun
167
168 @deffn Command compile-defun &optional arg
169 This command reads the defun containing point, compiles it, and
170 evaluates the result.  If you use this on a defun that is actually a
171 function definition, the effect is to install a compiled version of that
172 function.
173
174 @c XEmacs feature
175 If @var{arg} is non-@code{nil}, the result is inserted in the current
176 buffer after the form; otherwise, it is printed in the minibuffer.
177 @end deffn
178
179 @deffn Command byte-compile-file filename &optional load
180 This function compiles a file of Lisp code named @var{filename} into
181 a file of byte-code.  The output file's name is made by appending
182 @samp{c} to the end of @var{filename}.
183
184 @c XEmacs feature
185   If @code{load} is non-@code{nil}, the file is loaded after having been
186 compiled.
187
188 Compilation works by reading the input file one form at a time.  If it
189 is a definition of a function or macro, the compiled function or macro
190 definition is written out.  Other forms are batched together, then each
191 batch is compiled, and written so that its compiled code will be
192 executed when the file is read.  All comments are discarded when the
193 input file is read.
194
195 This command returns @code{t}.  When called interactively, it prompts
196 for the file name.
197
198 @example
199 @group
200 % ls -l push*
201 -rw-r--r--  1 lewis     791 Oct  5 20:31 push.el
202 @end group
203
204 @group
205 (byte-compile-file "~/emacs/push.el")
206      @result{} t
207 @end group
208
209 @group
210 % ls -l push*
211 -rw-r--r--  1 lewis     791 Oct  5 20:31 push.el
212 -rw-r--r--  1 lewis     638 Oct  8 20:25 push.elc
213 @end group
214 @end example
215 @end deffn
216
217 @c flag is not optional in FSF Emacs
218 @deffn Command byte-recompile-directory directory &optional flag norecursion force
219 @cindex library compilation
220 This function recompiles every @samp{.el} file in @var{directory} that
221 needs recompilation.  A file needs recompilation if a @samp{.elc} file
222 exists but is older than the @samp{.el} file.
223
224 Files in subdirectories of @var{directory} are also processed unless
225 optional argument @var{norecursion} is non-@code{nil}.
226
227 When a @samp{.el} file has no corresponding @samp{.elc} file, then
228 @var{flag} says what to do.  If it is @code{nil}, these files are
229 ignored.  If it is non-@code{nil}, the user is asked whether to compile
230 each such file.
231
232 If the fourth optional argument @var{force} is non-@code{nil},
233 recompile every @samp{.el} file that already has a @samp{.elc} file.
234
235 The return value of this command is unpredictable.
236 @end deffn
237
238 @defun batch-byte-compile
239 This function runs @code{byte-compile-file} on files specified on the
240 command line.  This function must be used only in a batch execution of
241 Emacs, as it kills Emacs on completion.  An error in one file does not
242 prevent processing of subsequent files.  (The file that gets the error
243 will not, of course, produce any compiled code.)
244
245 @example
246 % xemacs -batch -f batch-byte-compile *.el
247 @end example
248 @end defun
249
250 @c XEmacs feature
251 @defun batch-byte-recompile-directory
252   This function is similar to @code{batch-byte-compile} but runs the
253 command @code{byte-recompile-directory} on the files remaining on the
254 command line.
255 @end defun
256
257 @c XEmacs feature
258 @defvar byte-recompile-directory-ignore-errors-p
259   When non-@code{nil}, @code{byte-recompile-directory} will continue
260 compiling even when an error occurs in a file.  Default: @code{nil}, but
261 bound to @code{t} by @code{batch-byte-recompile-directory}.
262 @end defvar
263
264 @c XEmacs feature (?)
265 @defvar byte-recompile-directory-recursively
266    When non-@code{nil}, @code{byte-recompile-directory} will recurse on
267 subdirectories.  Default: @code{t}.
268 @end defvar
269
270
271 @defun byte-code instructions constants stack-depth
272 @cindex byte-code interpreter
273 This function actually interprets byte-code.
274 Don't call this function yourself.  Only the byte compiler knows how to
275 generate valid calls to this function.
276
277 In newer Emacs versions (19 and up), byte code is usually executed as
278 part of a compiled-function object, and only rarely due to an explicit
279 call to @code{byte-code}.  A byte-compiled function was once actually
280 defined with a body that calls @code{byte-code}, but in recent versions
281 of Emacs @code{byte-code} is only used to run isolated fragments of lisp
282 code without an associated argument list.
283 @end defun
284
285 @node Compilation Options
286 @section Options for the Byte Compiler
287 @cindex compilation options
288
289 Warning: this node is a quick draft based on docstrings.  There may be
290 inaccuracies, as the docstrings occasionally disagree with each other.
291 This has not been checked yet.
292
293 The byte compiler and optimizer are controlled by the following
294 variables.  The @code{byte-compiler-options} macro described below
295 provides a convenient way to set most of them on a file-by-file basis.
296
297 @defvar emacs-lisp-file-regexp
298 Regexp which matches Emacs Lisp source files.
299 You may want to redefine @code{byte-compile-dest-file} if you change
300 this.  Default: @code{"\\.el$"}.
301 @end defvar
302
303 @defun byte-compile-dest-file filename
304 Convert an Emacs Lisp source file name to a compiled file name.  This
305 function may be redefined by the user, if necessary, for compatibility
306 with @code{emacs-lisp-file-regexp}.
307 @end defun
308
309 @c ;; This can be the 'byte-compile property of any symbol.
310 @c (autoload 'byte-compile-inline-expand "byte-optimize")
311
312 @defvar byte-compile-verbose
313 When non-@code{nil}, print messages describing progress of
314 byte-compiler.  Default: @code{t} if interactive on a not-too-slow
315 terminal (see @code{search-slow-speed}), otherwise @code{nil}.
316 @end defvar
317
318 @defvar byte-optimize
319 Level of optimization in the byte compiler.
320
321 @table @code
322 @item nil
323 Do no optimization.
324
325 @item t
326 Do all optimizations.
327
328 @item source
329 Do optimizations manipulating the source code only.
330
331 @item byte
332 Do optimizations manipulating the byte code (actually, LAP code) only.
333 @end table
334 Default: @code{t}.
335 @end defvar
336
337 @defvar byte-compile-delete-errors
338 When non-@code{nil}, the optimizer may delete forms that may signal an
339 error if that is the only change in the function's behavior.
340 This includes variable references and calls to functions such as
341 @code{car}.
342 Default: @code{t}.
343 @end defvar
344
345 @defvar byte-optimize-log nil
346 When non-@code{nil}, the byte-compiler logs optimizations into
347 @file{*Compile-Log*}.
348
349 @table @code
350 @item nil
351 Log no optimization.
352
353 @item t
354 Log all optimizations.
355
356 @item source
357 Log optimizations manipulating the source code only.
358
359 @item byte
360 Log optimizations manipulating the byte code (actually, LAP code) only.
361 @end table
362 Default: @code{nil}.
363 @end defvar
364
365 @defvar byte-compile-error-on-warn
366 When non-@code{nil}, the byte-compiler reports warnings with @code{error}.
367 Default:  @code{nil}.
368 @end defvar
369
370 @defvar byte-compile-default-warnings
371 The warnings used when @code{byte-compile-warnings} is @code{t}.  Called
372 @code{byte-compile-warning-types} in GNU Emacs.
373 Default: @code{(redefine callargs subr-callargs free-vars unresolved
374 unused-vars obsolete)}.
375 @end defvar
376
377 @defvar byte-compile-warnings
378
379 List of warnings that the compiler should issue (@code{t} for the
380 default set).  Elements of the list may be:
381
382 @table @code
383 @item free-vars
384 References to variables not in the current lexical scope.
385
386 @item unused-vars
387 References to non-global variables bound but not referenced.
388
389 @item unresolved
390 Calls to unknown functions.
391
392 @item callargs
393 Lambda calls with args that don't match the definition.
394
395 @item subr-callargs
396 Calls to subrs with args that don't match the definition.
397
398 @item redefine
399 Function cell redefined from a macro to a lambda or vice
400 versa, or redefined to take a different number of arguments.
401
402 @item obsolete
403 Use of an obsolete function or variable.
404
405 @item pedantic
406 Warn of use of compatible symbols.
407 @end table
408
409 The default set is specified by @code{byte-compile-default-warnings} and
410 normally encompasses all possible warnings.
411
412 See also the macro @code{byte-compiler-options}.  Default: @code{t}.
413 @end defvar
414
415 The compiler can generate a call graph, which gives information about
416 which functions call which functions.
417
418 @defvar byte-compile-generate-call-tree
419 When non-@code{nil}, the compiler generates a call graph.  This records
420 functions that were called and from where.  If the value is @code{t},
421 compilation displays the call graph when it finishes.  If the value is
422 neither @code{t} nor @code{nil}, compilation asks you whether to display
423 the graph.
424
425 The call tree only lists functions called, not macros used. Those
426 functions which the byte-code interpreter knows about directly
427 (@code{eq}, @code{cons}, etc.) are not reported.
428
429 The call tree also lists those functions which are not known to be called
430 (that is, to which no calls have been compiled).  Functions which can be
431 invoked interactively are excluded from this list.  Default: @code{nil}.
432 @end defvar
433
434 @defvar byte-compile-call-tree nil
435
436 Alist of functions and their call tree, used internally.
437 Each element takes the form
438
439   (@var{function} @var{callers} @var{calls})
440
441 where @var{callers} is a list of functions that call @var{function}, and
442 @var{calls} is a list of functions for which calls were generated while
443 compiling @var{function}.
444 @end defvar
445
446 @defvar byte-compile-call-tree-sort
447 When non-@code{nil}, sort the call tree.  The values @code{name},
448 @code{callers}, @code{calls}, and @code{calls+callers} specify different
449 fields to sort on.")  Default: @code{name}.
450 @end defvar
451
452 @code{byte-compile-overwrite-file} controls treatment of existing
453 compiled files.
454
455 @defvar byte-compile-overwrite-file
456 When non-@code{nil}, do not preserve backups of @file{.elc}s.
457 Precisely, if @code{nil}, old @file{.elc} files are deleted before the
458 new one is saved, and @file{.elc} files will have the same modes as the
459 corresponding @file{.el} file.  Otherwise, existing @file{.elc} files
460 will simply be overwritten, and the existing modes will not be changed.
461 If this variable is @code{nil}, then an @file{.elc} file which is a
462 symbolic link will be turned into a normal file, instead of the file
463 which the link points to being overwritten.  Default: @code{t}.
464 @end defvar
465
466 Variables controlling recompiling directories are described elsewhere
467 @xref{Compilation Functions}.  They are
468 @code{byte-recompile-directory-ignore-errors-p} and
469 @code{byte-recompile-directory-recursively}.
470
471 The dynamic loading features are described elsewhere.  These are
472 controlled by the variables @code{byte-compile-dynamic} (@pxref{Dynamic
473 Loading}) and @code{byte-compile-dynamic-docstrings} (@pxref{Docs and
474 Compilation}).
475
476 The byte compiler is a relatively recent development, and has evolved
477 significantly over the period covering Emacs versions 19 and 20.  The
478 following variables control use of newer functionality by the byte
479 compiler.  These are rarely needed since the release of XEmacs 21.
480
481 Another set of compatibility issues arises between Mule and non-Mule
482 XEmacsen; there are no known compatibility issues specific to the byte
483 compiler.  There are also compatibility issues between XEmacs and GNU
484 Emacs's versions of the byte compiler.  While almost all of the byte
485 codes are the same, and code compiled by one version often runs
486 perfectly well on the other, this is very dangerous, and can result in
487 crashes or data loss.  Always recompile your Lisp when moving between
488 XEmacs and GNU Emacs.
489
490 @defvar byte-compile-single-version nil
491 When non-@code{nil}, the choice of emacs version (v19 or v20) byte-codes
492 will be hard-coded into bytecomp when it compiles itself.  If the
493 compiler itself is compiled with optimization, this causes a speedup.
494 Default: @code{nil}.
495 @end defvar
496
497 @defvar byte-compile-emacs19-compatibility
498 When non-@code{nil} generate output that can run in Emacs 19.
499 Default: @code{nil} when Emacs version is 20 or above, otherwise
500 @code{t}.
501 @end defvar
502
503 @defvar byte-compile-print-gensym
504 When non-@code{nil}, the compiler may generate code that creates unique
505 symbols at run-time.  This is achieved by printing uninterned symbols
506 using the @code{#:@var{}} notation, so that they will be read uninterned
507 when run.
508
509 With this feature, code that uses uninterned symbols in macros will
510 not be runnable under pre-21.0 XEmacsen.
511
512 Default: When @code{byte-compile-emacs19-compatibility} is non-nil, this
513 variable is ignored and considered to be @code{nil}.  Otherwise
514 @code{t}.
515 @end defvar
516
517 @defvar byte-compile-new-bytecodes
518 This is completely ignored.  For backwards compatibility.
519 @end defvar
520
521 @defun byte-compiler-options &rest args
522 Set some compilation-parameters for this file.  
523 This will affect only the file in which it appears; this does nothing when
524 evaluated, or when loaded from a @file{.el} file.
525
526 Each argument to this macro must be a list of a key and a value.
527 (#### Need to check whether the newer variables are settable here.)
528
529 @example
530   Keys:           Values:               Corresponding variable:
531
532   verbose         t, nil                byte-compile-verbose
533   optimize        t, nil, source, byte  byte-optimize
534   warnings        list of warnings      byte-compile-warnings
535   file-format     emacs19, emacs20      byte-compile-emacs19-compatibility
536 @end example
537
538 The value specified with the @code{warnings}option must be a list,
539 containing some subset of the following flags:
540
541 @example
542   free-vars     references to variables not in the current lexical scope.
543   unused-vars   references to non-global variables bound but not referenced.
544   unresolved    calls to unknown functions.
545   callargs      lambda calls with args that don't match the definition.
546   redefine      function cell redefined from a macro to a lambda or vice
547                 versa, or redefined to take a different number of arguments.
548 @end example
549
550 If the first element if the list is @code{+} or `@code{} then the
551 specified elements are added to or removed from the current set of
552 warnings, instead of the entire set of warnings being overwritten.
553 (#### Need to check whether the newer warnings are settable here.)
554
555 For example, something like this might appear at the top of a source file:
556
557 @example
558     (byte-compiler-options
559       (optimize t)
560       (warnings (- callargs))           ; Don't warn about arglist mismatch
561       (warnings (+ unused-vars))        ; Do warn about unused bindings
562       (file-format emacs19))
563 @end example
564 @end defun
565
566 @node Docs and Compilation
567 @section Documentation Strings and Compilation
568 @cindex dynamic loading of documentation
569
570   Functions and variables loaded from a byte-compiled file access their
571 documentation strings dynamically from the file whenever needed.  This
572 saves space within Emacs, and makes loading faster because the
573 documentation strings themselves need not be processed while loading the
574 file.  Actual access to the documentation strings becomes slower as a
575 result, but normally not enough to bother users.
576
577   Dynamic access to documentation strings does have drawbacks:
578
579 @itemize @bullet
580 @item
581 If you delete or move the compiled file after loading it, Emacs can no
582 longer access the documentation strings for the functions and variables
583 in the file.
584
585 @item
586 If you alter the compiled file (such as by compiling a new version),
587 then further access to documentation strings in this file will give
588 nonsense results.
589 @end itemize
590
591   If your site installs Emacs following the usual procedures, these
592 problems will never normally occur.  Installing a new version uses a new
593 directory with a different name; as long as the old version remains
594 installed, its files will remain unmodified in the places where they are
595 expected to be.
596
597   However, if you have built Emacs yourself and use it from the
598 directory where you built it, you will experience this problem
599 occasionally if you edit and recompile Lisp files.  When it happens, you
600 can cure the problem by reloading the file after recompiling it.
601
602   Versions of Emacs up to and including XEmacs 19.14 and FSF Emacs 19.28
603 do not support the dynamic docstrings feature, and so will not be able
604 to load bytecode created by more recent Emacs versions.  You can turn
605 off the dynamic docstring feature by setting
606 @code{byte-compile-dynamic-docstrings} to @code{nil}.  Once this is
607 done, you can compile files that will load into older Emacs versions.
608 You can do this globally, or for one source file by specifying a
609 file-local binding for the variable.  Here's one way to do that:
610
611 @example
612 -*-byte-compile-dynamic-docstrings: nil;-*-
613 @end example
614
615 @defvar byte-compile-dynamic-docstrings
616 If this is non-@code{nil}, the byte compiler generates compiled files
617 that are set up for dynamic loading of documentation strings.
618 Default: t.
619 @end defvar
620
621 @cindex @samp{#@@@var{count}}
622 @cindex @samp{#$}
623   The dynamic documentation string feature writes compiled files that
624 use a special Lisp reader construct, @samp{#@@@var{count}}.  This
625 construct skips the next @var{count} characters.  It also uses the
626 @samp{#$} construct, which stands for ``the name of this file, as a
627 string.''  It is best not to use these constructs in Lisp source files.
628
629 @node Dynamic Loading
630 @section Dynamic Loading of Individual Functions
631
632 @cindex dynamic loading of functions
633 @cindex lazy loading
634   When you compile a file, you can optionally enable the @dfn{dynamic
635 function loading} feature (also known as @dfn{lazy loading}).  With
636 dynamic function loading, loading the file doesn't fully read the
637 function definitions in the file.  Instead, each function definition
638 contains a place-holder which refers to the file.  The first time each
639 function is called, it reads the full definition from the file, to
640 replace the place-holder.
641
642   The advantage of dynamic function loading is that loading the file
643 becomes much faster.  This is a good thing for a file which contains
644 many separate commands, provided that using one of them does not imply
645 you will soon (or ever) use the rest.  A specialized mode which provides
646 many keyboard commands often has that usage pattern: a user may invoke
647 the mode, but use only a few of the commands it provides.
648
649   The dynamic loading feature has certain disadvantages:
650
651 @itemize @bullet
652 @item
653 If you delete or move the compiled file after loading it, Emacs can no
654 longer load the remaining function definitions not already loaded.
655
656 @item
657 If you alter the compiled file (such as by compiling a new version),
658 then trying to load any function not already loaded will get nonsense
659 results.
660 @end itemize
661
662   If you compile a new version of the file, the best thing to do is
663 immediately load the new compiled file.  That will prevent any future
664 problems.
665
666   The byte compiler uses the dynamic function loading feature if the
667 variable @code{byte-compile-dynamic} is non-@code{nil} at compilation
668 time.  Do not set this variable globally, since dynamic loading is
669 desirable only for certain files.  Instead, enable the feature for
670 specific source files with file-local variable bindings, like this:
671
672 @example
673 -*-byte-compile-dynamic: t;-*-
674 @end example
675
676 @defvar byte-compile-dynamic
677 If this is non-@code{nil}, the byte compiler generates compiled files
678 that are set up for dynamic function loading.
679 Default: nil.
680 @end defvar
681
682 @defun fetch-bytecode function
683 This immediately finishes loading the definition of @var{function} from
684 its byte-compiled file, if it is not fully loaded already.  The argument
685 @var{function} may be a compiled-function object or a function name.
686 @end defun
687
688 @node Eval During Compile
689 @section Evaluation During Compilation
690
691   These features permit you to write code to be evaluated during
692 compilation of a program.
693
694 @defspec eval-and-compile body
695 This form marks @var{body} to be evaluated both when you compile the
696 containing code and when you run it (whether compiled or not).
697
698 You can get a similar result by putting @var{body} in a separate file
699 and referring to that file with @code{require}.  Using @code{require} is
700 preferable if there is a substantial amount of code to be executed in
701 this way.
702 @end defspec
703
704 @defspec eval-when-compile body
705 This form marks @var{body} to be evaluated at compile time and not when
706 the compiled program is loaded.  The result of evaluation by the
707 compiler becomes a constant which appears in the compiled program.  When
708 the program is interpreted, not compiled at all, @var{body} is evaluated
709 normally.
710
711 At top level, this is analogous to the Common Lisp idiom
712 @code{(eval-when (compile eval) @dots{})}.  Elsewhere, the Common Lisp
713 @samp{#.} reader macro (but not when interpreting) is closer to what
714 @code{eval-when-compile} does.
715 @end defspec
716
717 @node Compiled-Function Objects
718 @section Compiled-Function Objects
719 @cindex compiled function
720 @cindex byte-code function
721
722   Byte-compiled functions have a special data type: they are
723 @dfn{compiled-function objects}. The evaluator handles this data type
724 specially when it appears as a function to be called.
725
726   The printed representation for a compiled-function object normally
727 begins with @samp{#<compiled-function} and ends with @samp{>}.  However,
728 if the variable @code{print-readably} is non-@code{nil}, the object is
729 printed beginning with @samp{#[} and ending with @samp{]}.  This
730 representation can be read directly by the Lisp reader, and is used in
731 byte-compiled files (those ending in @samp{.elc}).
732
733   In Emacs version 18, there was no compiled-function object data type;
734 compiled functions used the function @code{byte-code} to run the byte
735 code.
736
737   A compiled-function object has a number of different attributes.
738 They are:
739
740 @table @var
741 @item arglist
742 The list of argument symbols.
743
744 @item instructions
745 The string containing the byte-code instructions.
746
747 @item constants
748 The vector of Lisp objects referenced by the byte code.  These include
749 symbols used as function names and variable names.
750
751 @item stack-depth
752 The maximum stack size this function needs.
753
754 @item doc-string
755 The documentation string (if any); otherwise, @code{nil}.  The value may
756 be a number or a list, in case the documentation string is stored in a
757 file.  Use the function @code{documentation} to get the real
758 documentation string (@pxref{Accessing Documentation}).
759
760 @item interactive
761 The interactive spec (if any).  This can be a string or a Lisp
762 expression.  It is @code{nil} for a function that isn't interactive.
763
764 @item domain
765 The domain (if any).  This is only meaningful if I18N3 (message-translation)
766 support was compiled into XEmacs.  This is a string defining which
767 domain to find the translation for the documentation string and
768 interactive prompt.  @xref{Domain Specification}.
769 @end table
770
771 Here's an example of a compiled-function object, in printed
772 representation.  It is the definition of the command
773 @code{backward-sexp}.
774
775 @example
776 (symbol-function 'backward-sexp)
777 @result{} #<compiled-function
778 (&optional arg)
779 "...(15)" [arg 1 forward-sexp] 2 854740 "_p">
780 @end example
781
782   The primitive way to create a compiled-function object is with
783 @code{make-byte-code}:
784
785 @defun make-byte-code arglist instructions constants stack-depth &optional doc-string interactive
786 This function constructs and returns a compiled-function object
787 with the specified attributes.
788
789 @emph{Please note:} Unlike all other Emacs-lisp functions, calling this with
790 five arguments is @emph{not} the same as calling it with six arguments,
791 the last of which is @code{nil}.  If the @var{interactive} arg is
792 specified as @code{nil}, then that means that this function was defined
793 with @code{(interactive)}.  If the arg is not specified, then that means
794 the function is not interactive.  This is terrible behavior which is
795 retained for compatibility with old @samp{.elc} files which expected
796 these semantics.
797 @end defun
798
799   You should not try to come up with the elements for a compiled-function
800 object yourself, because if they are inconsistent, XEmacs may crash
801 when you call the function.  Always leave it to the byte compiler to
802 create these objects; it makes the elements consistent (we hope).
803
804   The following primitives are provided for accessing the elements of
805 a compiled-function object.
806
807 @defun compiled-function-arglist function
808 This function returns the argument list of compiled-function object
809 @var{function}.
810 @end defun
811
812 @defun compiled-function-instructions function
813 This function returns a string describing the byte-code instructions
814 of compiled-function object @var{function}.
815 @end defun
816
817 @defun compiled-function-constants function
818 This function returns the vector of Lisp objects referenced by
819 compiled-function object @var{function}.
820 @end defun
821
822 @defun compiled-function-stack-depth function
823 This function returns the maximum stack size needed by compiled-function
824 object @var{function}.
825 @end defun
826
827 @defun compiled-function-doc-string function
828 This function returns the doc string of compiled-function object
829 @var{function}, if available.
830 @end defun
831
832 @defun compiled-function-interactive function
833 This function returns the interactive spec of compiled-function object
834 @var{function}, if any.  The return value is @code{nil} or a two-element
835 list, the first element of which is the symbol @code{interactive} and
836 the second element is the interactive spec (a string or Lisp form).
837 @end defun
838
839 @defun compiled-function-domain function
840 This function returns the domain of compiled-function object
841 @var{function}, if any.  The result will be a string or @code{nil}.
842 @xref{Domain Specification}.
843 @end defun
844
845 @node Disassembly
846 @section Disassembled Byte-Code
847 @cindex disassembled byte-code
848
849   People do not write byte-code; that job is left to the byte compiler.
850 But we provide a disassembler to satisfy a cat-like curiosity.  The
851 disassembler converts the byte-compiled code into humanly readable
852 form.
853
854   The byte-code interpreter is implemented as a simple stack machine.
855 It pushes values onto a stack of its own, then pops them off to use them
856 in calculations whose results are themselves pushed back on the stack.
857 When a byte-code function returns, it pops a value off the stack and
858 returns it as the value of the function.
859
860   In addition to the stack, byte-code functions can use, bind, and set
861 ordinary Lisp variables, by transferring values between variables and
862 the stack.
863
864 @deffn Command disassemble object &optional stream
865 This function prints the disassembled code for @var{object}.  If
866 @var{stream} is supplied, then output goes there.  Otherwise, the
867 disassembled code is printed to the stream @code{standard-output}.  The
868 argument @var{object} can be a function name or a lambda expression.
869
870 As a special exception, if this function is used interactively,
871 it outputs to a buffer named @samp{*Disassemble*}.
872 @end deffn
873
874   Here are two examples of using the @code{disassemble} function.  We
875 have added explanatory comments to help you relate the byte-code to the
876 Lisp source; these do not appear in the output of @code{disassemble}.
877
878 @example
879 @group
880 (defun factorial (integer)
881   "Compute factorial of an integer."
882   (if (= 1 integer) 1
883     (* integer (factorial (1- integer)))))
884      @result{} factorial
885 @end group
886
887 @group
888 (factorial 4)
889      @result{} 24
890 @end group
891
892 @group
893 (disassemble 'factorial)
894      @print{} byte-code for factorial:
895  doc: Compute factorial of an integer.
896  args: (integer)
897 @end group
898
899 @group
900 0   varref   integer        ; @r{Get value of @code{integer}}
901                             ;   @r{from the environment}
902                             ;   @r{and push the value}
903                             ;   @r{onto the stack.}
904
905 1   constant 1              ; @r{Push 1 onto stack.}
906 @end group
907
908 @group
909 2   eqlsign                 ; @r{Pop top two values off stack,}
910                             ;   @r{compare them,}
911                             ;   @r{and push result onto stack.}
912 @end group
913
914 @group
915 3   goto-if-nil 1           ; @r{Pop and test top of stack;}
916                             ;   @r{if @code{nil},}
917                             ;   @r{go to label 1 (which is also byte 7),}
918                             ;   @r{else continue.}
919 @end group
920
921 @group
922 5   constant 1              ; @r{Push 1 onto top of stack.}
923
924 6   return                  ; @r{Return the top element}
925                             ;   @r{of the stack.}
926 @end group
927
928 7:1 varref   integer        ; @r{Push value of @code{integer} onto stack.}
929
930 @group
931 8   constant factorial      ; @r{Push @code{factorial} onto stack.}
932
933 9   varref   integer        ; @r{Push value of @code{integer} onto stack.}
934
935 10  sub1                    ; @r{Pop @code{integer}, decrement value,}
936                             ;   @r{push new value onto stack.}
937 @end group
938
939 @group
940                             ; @r{Stack now contains:}
941                             ;   @minus{} @r{decremented value of @code{integer}}
942                             ;   @minus{} @r{@code{factorial}}
943                             ;   @minus{} @r{value of @code{integer}}
944 @end group
945
946 @group
947 15  call     1              ; @r{Call function @code{factorial} using}
948                             ;   @r{the first (i.e., the top) element}
949                             ;   @r{of the stack as the argument;}
950                             ;   @r{push returned value onto stack.}
951 @end group
952
953 @group
954                             ; @r{Stack now contains:}
955                             ;   @minus{} @r{result of recursive}
956                             ;        @r{call to @code{factorial}}
957                             ;   @minus{} @r{value of @code{integer}}
958 @end group
959
960 @group
961 12  mult                    ; @r{Pop top two values off the stack,}
962                             ;   @r{multiply them,}
963                             ;   @r{pushing the result onto the stack.}
964 @end group
965
966 @group
967 13  return                  ; @r{Return the top element}
968                             ;   @r{of the stack.}
969      @result{} nil
970 @end group
971 @end example
972
973 The @code{silly-loop} function is somewhat more complex:
974
975 @example
976 @group
977 (defun silly-loop (n)
978   "Return time before and after N iterations of a loop."
979   (let ((t1 (current-time-string)))
980     (while (> (setq n (1- n))
981               0))
982     (list t1 (current-time-string))))
983      @result{} silly-loop
984 @end group
985
986 @group
987 (disassemble 'silly-loop)
988      @print{} byte-code for silly-loop:
989  doc: Return time before and after N iterations of a loop.
990  args: (n)
991
992 0   constant current-time-string  ; @r{Push}
993                                   ;   @r{@code{current-time-string}}
994                                   ;   @r{onto top of stack.}
995 @end group
996
997 @group
998 1   call     0              ; @r{Call @code{current-time-string}}
999                             ;   @r{ with no argument,}
1000                             ;   @r{ pushing result onto stack.}
1001 @end group
1002
1003 @group
1004 2   varbind  t1             ; @r{Pop stack and bind @code{t1}}
1005                             ;   @r{to popped value.}
1006 @end group
1007
1008 @group
1009 3:1 varref   n              ; @r{Get value of @code{n} from}
1010                             ;   @r{the environment and push}
1011                             ;   @r{the value onto the stack.}
1012 @end group
1013
1014 @group
1015 4   sub1                    ; @r{Subtract 1 from top of stack.}
1016 @end group
1017
1018 @group
1019 5   dup                     ; @r{Duplicate the top of the stack;}
1020                             ;   @r{i.e., copy the top of}
1021                             ;   @r{the stack and push the}
1022                             ;   @r{copy onto the stack.}
1023
1024 6   varset   n              ; @r{Pop the top of the stack,}
1025                             ;   @r{and set @code{n} to the value.}
1026
1027                             ; @r{In effect, the sequence @code{dup varset}}
1028                             ;   @r{copies the top of the stack}
1029                             ;   @r{into the value of @code{n}}
1030                             ;   @r{without popping it.}
1031 @end group
1032
1033 @group
1034 7   constant 0              ; @r{Push 0 onto stack.}
1035
1036 8   gtr                     ; @r{Pop top two values off stack,}
1037                             ;   @r{test if @var{n} is greater than 0}
1038                             ;   @r{and push result onto stack.}
1039 @end group
1040
1041 @group
1042 9   goto-if-not-nil 1       ; @r{Goto label 1 (byte 3) if @code{n} <= 0}
1043                             ;   @r{(this exits the while loop).}
1044                             ;   @r{else pop top of stack}
1045                             ;   @r{and continue}
1046 @end group
1047
1048 @group
1049 11  varref   t1             ; @r{Push value of @code{t1} onto stack.}
1050 @end group
1051
1052 @group
1053 12  constant current-time-string  ; @r{Push}
1054                                   ;   @r{@code{current-time-string}}
1055                                   ;   @r{onto top of stack.}
1056 @end group
1057
1058 @group
1059 13  call     0              ; @r{Call @code{current-time-string} again.}
1060
1061 14  unbind   1              ; @r{Unbind @code{t1} in local environment.}
1062 @end group
1063
1064 @group
1065 15  list2                   ; @r{Pop top two elements off stack,}
1066                             ;   @r{create a list of them,}
1067                             ;   @r{and push list onto stack.}
1068 @end group
1069
1070 @group
1071 16  return                  ; @r{Return the top element of the stack.}
1072
1073      @result{} nil
1074 @end group
1075 @end example
1076
1077
1078 @node Different Behavior
1079 @section Different Behavior
1080
1081 The intent is that compiled byte-code and the corresponding code
1082 executed by the Lisp interpreter produce identical results.  However,
1083 there are some circumstances where the results will differ.
1084
1085 @itemize @bullet
1086 @item
1087 Arithmetic operations may be rearranged for efficiency or compile-time
1088 evaluation.  When floating point numbers are involved, this may produce
1089 different values or an overflow.
1090 @item
1091 Some arithmetic operations may be optimized away.  For example, the
1092 expression @code{(+ x)} may be optimized to simply @code{x}.  If the
1093 value of @code{x} is a marker, then the value will be a marker instead
1094 of an integer.  If the value of @samp{x} is a cons cell, then the
1095 interpreter will issue an error, while the bytecode will not.
1096
1097 If you're trying to use @samp{(+ @var{object} 0)} to convert
1098 @var{object} to integer, consider using an explicit conversion function,
1099 which is clearer and guaranteed to work.
1100 Instead of @samp{(+ @var{marker} 0)}, use @samp{(marker-position @var{marker})}.
1101 Instead of @samp{(+ @var{char} 0)}, use @samp{(char-int @var{char})}.
1102 @end itemize
1103
1104 For maximal equivalence between interpreted and compiled code, the
1105 variables @code{byte-compile-delete-errors} and
1106 @code{byte-compile-optimize} can be set to @code{nil}, but this is not
1107 recommended.