21.3 Options for the Byte Compiler

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 byte-compiler-options macro described below provides a convenient way to set most of them on a file-by-file basis.

Variable: emacs-lisp-file-regexp

Regexp which matches Emacs Lisp source files. You may want to redefine byte-compile-dest-file if you change this. Default: "\\.el$".

Function: 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 emacs-lisp-file-regexp.

Variable: byte-compile-verbose

When non-nil, print messages describing progress of byte-compiler. Default: t if interactive on a not-too-slow terminal (see search-slow-speed), otherwise nil.

Variable: byte-optimize

Level of optimization in the byte compiler.

nil

Do no optimization.

t

Do all optimizations.

source

Do optimizations manipulating the source code only.

byte

Do optimizations manipulating the byte code (actually, LAP code) only.

Default: t.

Variable: byte-compile-delete-errors

When non-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 car. Default: t.

Variable: byte-optimize-log nil

When non-nil, the byte-compiler logs optimizations into *Compile-Log*.

nil

Log no optimization.

t

Log all optimizations.

source

Log optimizations manipulating the source code only.

byte

Log optimizations manipulating the byte code (actually, LAP code) only.

Default: nil.

Variable: byte-compile-error-on-warn

When non-nil, the byte-compiler reports warnings with error. Default: nil.

Variable: byte-compile-default-warnings

The warnings used when byte-compile-warnings is t. Called byte-compile-warning-types in GNU Emacs. Default: (redefine callargs subr-callargs free-vars unresolved unused-vars obsolete).

Variable: byte-compile-warnings

List of warnings that the compiler should issue (t for the default set). Elements of the list may be:

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.

subr-callargs

Calls to subrs 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.

obsolete

Use of an obsolete function or variable.

pedantic

Warn of use of compatible symbols.

The default set is specified by byte-compile-default-warnings and normally encompasses all possible warnings.

See also the macro byte-compiler-options. Default: t.

The compiler can generate a call graph, which gives information about which functions call which functions.

Variable: byte-compile-generate-call-tree

When non-nil, the compiler generates a call graph. This records functions that were called and from where. If the value is t, compilation displays the call graph when it finishes. If the value is neither t nor 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 (eq, 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: nil.

Variable: byte-compile-call-tree nil

Alist of functions and their call tree, used internally. Each element takes the form

(function callers calls)

where callers is a list of functions that call function, and calls is a list of functions for which calls were generated while compiling function.

Variable: byte-compile-call-tree-sort

When non-nil, sort the call tree. The values name, callers, calls, and calls+callers specify different fields to sort on.") Default: name.

byte-compile-overwrite-file controls treatment of existing compiled files.

Variable: byte-compile-overwrite-file

When non-nil, do not preserve backups of .elcs. Precisely, if nil, old .elc files are deleted before the new one is saved, and .elc files will have the same modes as the corresponding .el file. Otherwise, existing .elc files will simply be overwritten, and the existing modes will not be changed. If this variable is nil, then an .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: t.

Variables controlling recompiling directories are described elsewhere See Compilation Functions. They are byte-recompile-directory-ignore-errors-p and byte-recompile-directory-recursively.

The dynamic loading features are described elsewhere. These are controlled by the variables byte-compile-dynamic (see Dynamic Loading) and byte-compile-dynamic-docstrings (see 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 SXEmacs 22.

Another set of compatibility issues arises between Mule and non-Mule SXEmacsen; there are no known compatibility issues specific to the byte compiler. There are also compatibility issues between SXEmacs 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 SXEmacs, XEmacs and GNU Emacs.

Variable: byte-compile-emacs19-compatibility

When non-nil generate output that can run in Emacs 19. Default: nil

Variable: byte-compile-print-gensym

When non-nil, the compiler may generate code that creates unique symbols at run-time. This is achieved by printing uninterned symbols using the #: notation, so that they will be read uninterned when run.

Default: When byte-compile-emacs19-compatibility is non-nil, this variable is ignored and considered to be nil. Otherwise t.

Variable: byte-compile-new-bytecodes

This is completely ignored. For backwards compatibility.

Function: 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 .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.)

  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

The value specified with the warningsoption must be a list, containing some subset of the following flags:

  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.

If the first element if the list is + or ‘ 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:

    (byte-compiler-options
      (optimize t)
      (warnings (- callargs))		; Don't warn about arglist mismatch
      (warnings (+ unused-vars))	; Do warn about unused bindings
      (file-format emacs19))