GNU Info

(elisp)Compilation Functions

---

Next: Docs and Compilation Prev: Speed of Byte-Code Up: Byte Compilation

---

Enter node , (file) or (file)node

The Compilation Functions
=========================

   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'.

   The byte compiler produces error messages and warnings about each
file in a buffer called `*Compile-Log*'.  These report things in your
program that suggest a problem but are not necessarily erroneous.

   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 Note: Compiling Macros.  If a program does not work the
same way when compiled as it does when interpreted, erroneous macro
definitions are one likely cause (Note: Problems with 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
(Note: Named Features).  To avoid loading the macro definition files
when someone _runs_ the compiled program, write `eval-when-compile'
around the `require' calls (Note: 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 byte-code 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)
          =>
          #[(integer)
            "^H\301U\203^H^@\301\207\302^H\303^HS!\"\207"
            [integer 1 * factorial]
            4 "Compute factorial of INTEGER."]

     The result is a byte-code 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
     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.

 - Command: byte-compile-file filename
     This function compiles a file of Lisp code named FILENAME into a
     file of byte-code.  The output file's name is made by changing the
     `.el' suffix into `.elc'; if FILENAME does not end in `.el', it
     adds `.elc' to the end of 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 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-rw-rw-  1 lewis     638 Oct  8 20:25 push.elc

 - Command: byte-recompile-directory directory flag
     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.

     When a `.el' file has no corresponding `.elc' file, FLAG says what
     to do.  If it is `nil', these files are ignored.  If it is
     non-`nil', the user is asked whether to compile each such file.

     The returned 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, but no
     output file will be generated for it, and the Emacs process will
     terminate with a nonzero status code.

          % emacs -batch -f batch-byte-compile *.el

 - Function: byte-code code-string data-vector max-stack
     This function actually interprets byte-code.  A byte-compiled
     function is actually defined with a body that calls `byte-code'.
     Don't call this function yourself--only the byte compiler knows
     how to generate valid calls to this function.

     In Emacs version 18, byte-code was always executed by way of a
     call to the function `byte-code'.  Nowadays, byte-code is usually
     executed as part of a byte-code function object, and only rarely
     through an explicit call to `byte-code'.