Compilation Functions - SXEmacs Lisp Reference Manual

You can byte-compile an individual function or macro definition with the byte-compile function. You can compile a whole file with byte-compile-file, or several files with byte-recompile-directory or batch-byte-compile.

When you run the byte compiler, you may get warnings in a buffer called ‘*Compile-Log*’. These report things in your program that suggest a problem but are not necessarily erroneous.

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 Compiling Macros.

Normally, compiling a file does not evaluate the file's contents or load the file. But it does execute any require calls at top level in the file. One way to ensure that necessary macro definitions are available during compilation is to require the file that defines them (see Named Features). To avoid loading the macro definition files when someone runs the compiled program, write eval-when-compile around the require calls (see Eval During Compile).

— Function: byte-compile symbol

This function byte-compiles the function definition of symbol, replacing the previous definition with the compiled one. The function definition of symbol must be the actual code for the function; i.e., the compiler does not follow indirection to another symbol. byte-compile returns the new, compiled definition of symbol.
If symbol's definition is a compiled-function object, byte-compile does nothing and returns nil. Lisp records only one function definition for any symbol, and if that is already compiled, non-compiled code is not available anywhere. So there is no way to “compile the same definition again.”
          (defun factorial (integer)
            "Compute factorial of INTEGER."
            (if (= 1 integer) 1
              (* integer (factorial (1- integer)))))
          ⇒ factorial
          
          (byte-compile 'factorial)
          ⇒ #<compiled-function
          (integer)
          "...(21)"
          [integer 1 factorial]
          3
          "Compute factorial of INTEGER.">
The result is a compiled-function object. The string it contains is the actual byte-code; each character in it is an instruction or an operand of an instruction. The vector contains all the constants, variable names and function names used by the function, except for certain primitives that are coded as special instructions.

— Command: compile-defun &optional arg

This command reads the defun containing point, compiles it, and evaluates the result. If you use this on a defun that is actually a function definition, the effect is to install a compiled version of that function.
If arg is non-nil, the result is inserted in the current buffer after the form; otherwise, it is printed in the minibuffer.

— Command: byte-compile-file filename &optional load

This function compiles a file of Lisp code named filename into a file of byte-code. The output file's name is made by appending ‘c’ to the end of filename.
If load is non-nil, the file is loaded after having been compiled.
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 definition is written out. Other forms are batched together, then each batch is compiled, and written so that its compiled code will be executed when the file is read. All comments are discarded when the input file is read.
This command returns t. When called interactively, it prompts for the file name.
          % ls -l push*
          -rw-r--r--  1 lewis     791 Oct  5 20:31 push.el
          
          (byte-compile-file "~/emacs/push.el")
               ⇒ t
          
          % ls -l push*
          -rw-r--r--  1 lewis     791 Oct  5 20:31 push.el
          -rw-r--r--  1 lewis     638 Oct  8 20:25 push.elc

— Command: byte-recompile-directory directory &optional flag norecursion force

This function recompiles every ‘.el’ file in directory that needs recompilation. A file needs recompilation if a ‘.elc’ file exists but is older than the ‘.el’ file. Files in subdirectories of directory are processed depending on the variable byte-recompile-directory-recursively (which is t by default).
The optional second argument flag indicates what to do when a ‘.el’ file has no corresponding ‘.elc’ file. If it is nil, these files are ignored. If it is non-nil or an integer greater than 0, the user is asked whether to compile each such file. If it is 0 or less, the file in question is compiled quietly, i.e. the user is not asked. Note: flag is not optional in FSF Emacs.
If the third optional argument norecursion is non-nil, files in subdirectories are not processed. This may be unnecessary depending on the value of byte-recompile-directory-recursively.
If the fourth optional argument force is non-nil, recompile every ‘.el’ file that already has a ‘.elc’ file.
The return value of this command is unpredictable.

— Function: batch-byte-compile

This function runs 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.)
          % sxemacs -batch -f batch-byte-compile *.el

— Function: batch-byte-recompile-directory

This function is similar to batch-byte-compile but runs the command byte-recompile-directory on the files remaining on the command line.

— Variable: byte-recompile-directory-ignore-errors-p

When non-nil, byte-recompile-directory will continue compiling even when an error occurs in a file. Default: nil, but bound to t by batch-byte-recompile-directory.

— Variable: byte-recompile-directory-recursively

When non-nil, byte-recompile-directory will recurse on subdirectories. Default: t.

— Function: byte-code instructions constants stack-depth

This function actually interprets byte-code. Don't call this function yourself. Only the byte compiler knows how to generate valid calls to this function.
In all SXEmacs versions, and recent Emacs versions (19 and up), byte code is usually executed as part of a compiled-function object, and only rarely due to an explicit call to byte-code. A byte-compiled function was once actually defined with a body that calls byte-code, but in recent versions of Emacs byte-code is only used to run isolated fragments of lisp code without an associated argument list.

21.2 The Compilation Functions