(lispref.info)Compilation Functions


Next: Eval During Compile Up: Byte Compilation

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

   When you run the byte compiler, you may get warnings in a buffer
called `*Compile-Log*'.  These report usage 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 Note: Compiling
Macros.

   While byte-compiling a file, any `require' calls at top-level are
executed.  One way to ensure that necessary macro definitions are
available during compilation is to require the file that defines them.
Note: Features.

   A byte-compiled function is not as efficient as a primitive function
written in C, but runs much faster than the version written in Lisp.
For a rough comparison, consider the example below:

     (defun silly-loop (n)
       "Return time before and after N iterations of a loop."
       (let ((t1 (current-time-string)))
         (while (> (setq n (1- n))
                   0))
         (list t1 (current-time-string))))
     => silly-loop
     
     (silly-loop 100000)
     => ("Thu Jan 12 20:18:38 1989"
         "Thu Jan 12 20:19:29 1989")  ; 51 seconds
     
     (byte-compile 'silly-loop)
     => [Compiled code not shown]
     
     (silly-loop 100000)
     => ("Thu Jan 12 20:21:04 1989"
         "Thu Jan 12 20:21:17 1989")  ; 13 seconds

   In this example, the interpreted code required 51 seconds to run,
whereas the byte-compiled code required 13 seconds.  These results are
representative, but actual results will vary greatly.

 - 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' does not compile macros.
     `byte-compile' returns the new, compiled definition of SYMBOL.

          (defun factorial (integer)
            "Compute factorial of INTEGER."
            (if (= 1 integer) 1
              (* integer (factorial (1- integer)))))
               => factorial
          
          (byte-compile 'factorial)
               =>
          #<byte-code (integer)
           "US!_"
           [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.
     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-rw-rw-  1 lewis     638 Oct  8 20:25 push.elc

 - Command: byte-recompile-directory DIRECTORY &optional 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.

     If a `.el' file exists, but there is no corresponding `.elc' file,
     then FLAG is examined.  If it is `nil', the file is ignored.  If
     it is non-`nil', the user is asked whether the file should be
     compiled.

     The returned value of this command is unpredictable.

 - Function: batch-byte-compile
     This function runs `byte-compile-file' on the files remaining 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 which gets the error will not, of course, produce any
     compiled code.)

          % emacs -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
     If non-`nil', this specifies that `byte-recompile-directory' will
     continue compiling even when an error occurs in a file.  This is
     normally `nil', but is bound to `t' by
     `batch-byte-recompile-directory'.

 - 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 newer Emacs versions (19 and up), byte-code is usually executed
     as part of a compiled function object, and only rarely as part of
     a call to `byte-code'.


automatically generated by info2www