X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=man%2Flispref%2Fcompile.texi;h=d3f3cbe42d79a876265dab79314e1c7540e0f211;hb=e5faf85aac142013ef1a552b8a671f432ee4fd3f;hp=8d92bd0e0735e362e785d8d1632c00404c76e4f1;hpb=77dcef404dc78635f6ffa8f71a803d2bc7cc8921;p=chise%2Fxemacs-chise.git.1 diff --git a/man/lispref/compile.texi b/man/lispref/compile.texi index 8d92bd0..d3f3cbe 100644 --- a/man/lispref/compile.texi +++ b/man/lispref/compile.texi @@ -41,11 +41,13 @@ byte compilation. @menu * Speed of Byte-Code:: An example of speedup from byte compilation. * Compilation Functions:: Byte compilation functions. +* Compilation Options:: Controlling the byte compiler's behavior. * 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. * 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 @@ -213,17 +215,23 @@ for the file name. @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 @@ -235,7 +243,7 @@ prevent processing of subsequent files. (The file that gets the error will not, of course, produce any compiled code.) @example -% emacs -batch -f batch-byte-compile *.el +% xemacs -batch -f batch-byte-compile *.el @end example @end defun @@ -248,13 +256,19 @@ command line. @c XEmacs feature @defvar byte-recompile-directory-ignore-errors-p - If non-@code{nil}, this specifies that @code{byte-recompile-directory} -will continue compiling even when an error occurs in a file. This is -normally @code{nil}, but is bound to @code{t} by -@code{batch-byte-recompile-directory}. + When non-@code{nil}, @code{byte-recompile-directory} will continue +compiling even when an error occurs in a file. Default: @code{nil}, but +bound to @code{t} by @code{batch-byte-recompile-directory}. +@end defvar + +@c XEmacs feature (?) +@defvar byte-recompile-directory-recursively + When non-@code{nil}, @code{byte-recompile-directory} will recurse on +subdirectories. Default: @code{t}. @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 @@ -268,6 +282,287 @@ of Emacs @code{byte-code} is only used to run isolated fragments of lisp code without an associated argument list. @end defun +@node Compilation Options +@section Options for the Byte Compiler +@cindex compilation options + +Warning: this node is a quick draft based on docstrings. There may be +inaccuracies, as the docstrings occasionally disagree with each other. +This has not been checked yet. + +The byte compiler and optimizer are controlled by the following +variables. The @code{byte-compiler-options} macro described below +provides a convenient way to set most of them on a file-by-file basis. + +@defvar emacs-lisp-file-regexp +Regexp which matches Emacs Lisp source files. +You may want to redefine @code{byte-compile-dest-file} if you change +this. Default: @code{"\\.el$"}. +@end defvar + +@defun byte-compile-dest-file filename +Convert an Emacs Lisp source file name to a compiled file name. This +function may be redefined by the user, if necessary, for compatibility +with @code{emacs-lisp-file-regexp}. +@end defun + +@c ;; This can be the 'byte-compile property of any symbol. +@c (autoload 'byte-compile-inline-expand "byte-optimize") + +@defvar byte-compile-verbose +When non-@code{nil}, print messages describing progress of +byte-compiler. Default: @code{t} if interactive on a not-too-slow +terminal (see @code{search-slow-speed}), otherwise @code{nil}. +@end defvar + +@defvar byte-optimize +Level of optimization in the byte compiler. + +@table @code +@item nil +Do no optimization. + +@item t +Do all optimizations. + +@item source +Do optimizations manipulating the source code only. + +@item byte +Do optimizations manipulating the byte code (actually, LAP code) only. +@end table +Default: @code{t}. +@end defvar + +@defvar byte-compile-delete-errors +When non-@code{nil}, the optimizer may delete forms that may signal an +error if that is the only change in the function's behavior. +This includes variable references and calls to functions such as +@code{car}. +Default: @code{t}. +@end defvar + +@defvar byte-optimize-log nil +When non-@code{nil}, the byte-compiler logs optimizations into +@file{*Compile-Log*}. + +@table @code +@item nil +Log no optimization. + +@item t +Log all optimizations. + +@item source +Log optimizations manipulating the source code only. + +@item byte +Log optimizations manipulating the byte code (actually, LAP code) only. +@end table +Default: @code{nil}. +@end defvar + +@defvar byte-compile-error-on-warn +When non-@code{nil}, the byte-compiler reports warnings with @code{error}. +Default: @code{nil}. +@end defvar + +@defvar byte-compile-default-warnings +The warnings used when @code{byte-compile-warnings} is @code{t}. Called +@code{byte-compile-warning-types} in GNU Emacs. +Default: @code{(redefine callargs subr-callargs free-vars unresolved +unused-vars obsolete)}. +@end defvar + +@defvar byte-compile-warnings + +List of warnings that the compiler should issue (@code{t} for the +default set). Elements of the list may be: + +@table @code +@item free-vars +References to variables not in the current lexical scope. + +@item unused-vars +References to non-global variables bound but not referenced. + +@item unresolved +Calls to unknown functions. + +@item callargs +Lambda calls with args that don't match the definition. + +@item subr-callargs +Calls to subrs with args that don't match the definition. + +@item redefine +Function cell redefined from a macro to a lambda or vice +versa, or redefined to take a different number of arguments. + +@item obsolete +Use of an obsolete function or variable. + +@item pedantic +Warn of use of compatible symbols. +@end table + +The default set is specified by @code{byte-compile-default-warnings} and +normally encompasses all possible warnings. + +See also the macro @code{byte-compiler-options}. Default: @code{t}. +@end defvar + +The compiler can generate a call graph, which gives information about +which functions call which functions. + +@defvar byte-compile-generate-call-tree +When non-@code{nil}, the compiler generates a call graph. This records +functions that were called and from where. If the value is @code{t}, +compilation displays the call graph when it finishes. If the value is +neither @code{t} nor @code{nil}, compilation asks you whether to display +the graph. + +The call tree only lists functions called, not macros used. Those +functions which the byte-code interpreter knows about directly +(@code{eq}, @code{cons}, etc.) are not reported. + +The call tree also lists those functions which are not known to be called +(that is, to which no calls have been compiled). Functions which can be +invoked interactively are excluded from this list. Default: @code{nil}. +@end defvar + +@defvar byte-compile-call-tree nil + +Alist of functions and their call tree, used internally. +Each element takes the form + + (@var{function} @var{callers} @var{calls}) + +where @var{callers} is a list of functions that call @var{function}, and +@var{calls} is a list of functions for which calls were generated while +compiling @var{function}. +@end defvar + +@defvar byte-compile-call-tree-sort +When non-@code{nil}, sort the call tree. The values @code{name}, +@code{callers}, @code{calls}, and @code{calls+callers} specify different +fields to sort on.") Default: @code{name}. +@end defvar + +@code{byte-compile-overwrite-file} controls treatment of existing +compiled files. + +@defvar byte-compile-overwrite-file +When non-@code{nil}, do not preserve backups of @file{.elc}s. +Precisely, if @code{nil}, old @file{.elc} files are deleted before the +new one is saved, and @file{.elc} files will have the same modes as the +corresponding @file{.el} file. Otherwise, existing @file{.elc} files +will simply be overwritten, and the existing modes will not be changed. +If this variable is @code{nil}, then an @file{.elc} file which is a +symbolic link will be turned into a normal file, instead of the file +which the link points to being overwritten. Default: @code{t}. +@end defvar + +Variables controlling recompiling directories are described elsewhere +@xref{Compilation Functions}. They are +@code{byte-recompile-directory-ignore-errors-p} and +@code{byte-recompile-directory-recursively}. + +The dynamic loading features are described elsewhere. These are +controlled by the variables @code{byte-compile-dynamic} (@pxref{Dynamic +Loading}) and @code{byte-compile-dynamic-docstrings} (@pxref{Docs and +Compilation}). + +The byte compiler is a relatively recent development, and has evolved +significantly over the period covering Emacs versions 19 and 20. The +following variables control use of newer functionality by the byte +compiler. These are rarely needed since the release of XEmacs 21. + +Another set of compatibility issues arises between Mule and non-Mule +XEmacsen; there are no known compatibility issues specific to the byte +compiler. There are also compatibility issues between XEmacs and GNU +Emacs's versions of the byte compiler. While almost all of the byte +codes are the same, and code compiled by one version often runs +perfectly well on the other, this is very dangerous, and can result in +crashes or data loss. Always recompile your Lisp when moving between +XEmacs and GNU Emacs. + +@defvar byte-compile-single-version nil +When non-@code{nil}, the choice of emacs version (v19 or v20) byte-codes +will be hard-coded into bytecomp when it compiles itself. If the +compiler itself is compiled with optimization, this causes a speedup. +Default: @code{nil}. +@end defvar + +@defvar byte-compile-emacs19-compatibility +When non-@code{nil} generate output that can run in Emacs 19. +Default: @code{nil} when Emacs version is 20 or above, otherwise +@code{t}. +@end defvar + +@defvar byte-compile-print-gensym +When non-@code{nil}, the compiler may generate code that creates unique +symbols at run-time. This is achieved by printing uninterned symbols +using the @code{#:@var{}} notation, so that they will be read uninterned +when run. + +With this feature, code that uses uninterned symbols in macros will +not be runnable under pre-21.0 XEmacsen. + +Default: When @code{byte-compile-emacs19-compatibility} is non-nil, this +variable is ignored and considered to be @code{nil}. Otherwise +@code{t}. +@end defvar + +@defvar byte-compile-new-bytecodes +This is completely ignored. For backwards compatibility. +@end defvar + +@defun byte-compiler-options &rest args +Set some compilation-parameters for this file. +This will affect only the file in which it appears; this does nothing when +evaluated, or when loaded from a @file{.el} file. + +Each argument to this macro must be a list of a key and a value. +(#### Need to check whether the newer variables are settable here.) + +@example + Keys: Values: Corresponding variable: + + verbose t, nil byte-compile-verbose + optimize t, nil, source, byte byte-optimize + warnings list of warnings byte-compile-warnings + file-format emacs19, emacs20 byte-compile-emacs19-compatibility +@end example + +The value specified with the @code{warnings}option must be a list, +containing some subset of the following flags: + +@example + free-vars references to variables not in the current lexical scope. + unused-vars references to non-global variables bound but not referenced. + unresolved calls to unknown functions. + callargs lambda calls with args that don't match the definition. + redefine function cell redefined from a macro to a lambda or vice + versa, or redefined to take a different number of arguments. +@end example + +If the first element if the list is @code{+} or `@code{} then the +specified elements are added to or removed from the current set of +warnings, instead of the entire set of warnings being overwritten. +(#### Need to check whether the newer warnings are settable here.) + +For example, something like this might appear at the top of a source file: + +@example + (byte-compiler-options + (optimize t) + (warnings (- callargs)) ; Don't warn about arglist mismatch + (warnings (+ unused-vars)) ; Do warn about unused bindings + (file-format emacs19)) +@end example +@end defun + @node Docs and Compilation @section Documentation Strings and Compilation @cindex dynamic loading of documentation @@ -320,6 +615,7 @@ file-local binding for the variable. Here's one way to do that: @defvar byte-compile-dynamic-docstrings If this is non-@code{nil}, the byte compiler generates compiled files that are set up for dynamic loading of documentation strings. +Default: t. @end defvar @cindex @samp{#@@@var{count}} @@ -380,6 +676,7 @@ specific source files with file-local variable bindings, like this: @defvar byte-compile-dynamic If this is non-@code{nil}, the byte compiler generates compiled files that are set up for dynamic function loading. +Default: nil. @end defvar @defun fetch-bytecode function @@ -451,7 +748,7 @@ The string containing the byte-code instructions. 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 @@ -485,7 +782,7 @@ representation. It is the definition of the command 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. @@ -522,7 +819,7 @@ This function returns the vector of Lisp objects referenced by 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 @@ -778,3 +1075,33 @@ The @code{silly-loop} function is somewhat more complex: @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.