bytecode-commands.texi

@SECTION Functions and Commands for working with LAP and Bytecode

You can byte-compile an individual function or macro definition with
the @code{byte-compile} function. To extract individual components of
that array use @code{aref}. To recover human-readable LAP code from
a byte-compiled file use @code{dissasemble}. Perhaps in the future there
will be a decompiler which reconstructs higher-level Lisp from LAP.

You can see if a symbol's value holds one of the function types or an
alias to a function with @code{functionp}.  To retrieve the definition
of the function use @code{symbol-function}.

You can compile a buffer with @code{emacs-lisp-byte-compile},
or a whole file with @code{byte-compile-file}.

Several can be compiled with @code{byte-recompile-directory} or
@code{batch-byte-compile}.

@vindex byte-compile-debug
 Sometimes, the byte compiler produces warning and/or error messages
(@pxref{Compiler Errors,,,elisp, GNU Emacs Lisp Reference Manual}, for
details).  These messages are normally recorded in a buffer called
@file{*Compile-Log*}, which uses compilation mode.  @xref{Compilation
Mode,,,emacs, The GNU Emacs Manual}.  However, if the variable
@code{byte-compile-debug} is non-nil, error message will be signaled
as Lisp errors instead (@pxref{Errors,,,elisp, GNU Emacs Lisp
Reference Manual}).

@cindex macro compilation
Be careful when writing macro calls in files that you intend to
byte-compile.  Since macro calls are expanded when they are compiled,
the macros need to be loaded into Emacs or the byte compiler will not
do the right thing.  The usual way to handle this is with
@code{require} forms which specify the files containing the needed
macro definitions (@pxref{Named Features,,,elisp, GNU Emacs Lisp
Reference Manual}).  Normally, the byte compiler does not evaluate the
code that it is compiling, but it handles @code{require} forms
specially, by loading the specified libraries.  To avoid loading the
macro definition files when someone runs the compiled program,
write @code{eval-when-compile} around the @code{require} calls
(@pxref{Eval During Compile,,,elisp, GNU Emacs Lisp Reference
Manual}). @xref{Compiling Macros, , , elisp, The GNU Emacs Lisp Reference Manual} for more details.

Inline (@code{defsubst}) functions are less troublesome. If you
compile a call to such a function before its definition is known, the
call will still work right; it will just run slower.

In the list below, some of the functions are somewhat general and are
not specific to bytecode. however they are mentioned because they are
specifically have an interesting use in bytecode and their connection
might be readily appearent.

@menu
* aref-fn::  aref
* batch-byte-compile::
* batch-byte-recompile-directory::
* byte-code::
* byte-compile::
* byte-compile-file::
* byte-compile-sexp::
* byte-recalc-examples::
* byte-recompile-directory::
* byte-recompile-file::
* compile-defun::
* disassemble::
* disassemble-file::
* disassemble-full::
* display-call-tree::
* emacs-lisp-byte-compile::
* functionp::
* make-byte-code::
* symbol-function-fn:: symbol-function
@end menu

@node aref-fn
@subsection @code{aref}

@defun aref arry idx
Return the element of @var{array} at index @var{idx}.

Use this to extract the individual components of a byte-code object.
@xref{Emacs Lisp Bytecode Objects} for numerous examples using @code{aref}.
@end defun

@example
@group
ELISP> (aref
        (symbol-function 'cl-gcd)
        1) ;; 1 is the bytecode string field

"("/tmp/emacs/lisp/emacs-lisp/cl-extra.elc" . 7352)
@end group
@end example


@node batch-byte-compile
@subsection @code{batch-byte-compile}

@defun batch-byte-compile &optional noforce
This function runs @code{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.

If @var{noforce} is non-@code{nil}, this function does not recompile
files that have an up-to-date @samp{.elc} file.

@example
$ emacs -batch -f batch-byte-compile *.el
@end example
@end defun

@node batch-byte-recompile-directory
@subsection @code{batch-byte-recompile-directory}

@defun batch-byte-recompile-directory directory &optional arg
Run @code{byte-recompile-directory} on the dirs remaining on the command line.
Must be used only with @code{-batch}, and kills Emacs on completion.
For example, invoke @code{emacs -batch -f batch-byte-recompile-directory .}.

Optional argument @var{arg} is passed as second argument @var{arg} to
@code{byte-recompile-directory}; see there for its possible values
and corresponding effects.
@end defun

@node byte-code
@subsection @code{byte-code}

@defun byte-code bytestr vector maxdepth
This function is executes byte code and is used internally in
byte-compiled code.  The first argument, @var{bytestr}, is a string of
byte code; the second, @var{vector}, a vector of constants; the third,
@var{maxdepth}, the maximum stack depth used in this function.  If the
third argument is incorrect, Emacs may crash.
@end defun

@example
@group
ELISP> (setq msg-string "hi")
"hi"
ELISP> (byte-code "\301!\207" [msg-string message] 2)
"hi"
@end group
@end example


@node byte-compile
@subsection @code{byte-compile}

@deffn Command byte-compile form
If @var{form} is a symbol, byte-compile its function definition.

@example
@group
(defun factorial (integer)
  "Compute factorial of INTEGER."
  (if (= 1 integer) 1
    (* integer (factorial (1- integer)))))
@result{} factorial
@end group

@group
(byte-compile 'factorial)
@result{}
#[(integer)
  "^H\301U\203^H^@@\301\207\302^H\303^HS!\"\207"
  [integer 1 * factorial]
  4 "Compute factorial of INTEGER."]
@end group
@end example

If @var{form} is a lambda or a macro, byte-compile it as a function.

@example
@group
(byte-compile
  (lambda (a) (* a a)))
@result{}
  #[(a) "^H\211\207" [a] 2]
@end group
@end example

If @var{symbol}'s definition is a bytecode function object,
@code{byte-compile} does nothing and returns @code{nil}.  It does not
compile the symbol's definition again, since the original
(non-compiled) code has already been replaced in the symbol's function
cell by the byte-compiled code.

@end deffn


@node byte-compile-file
@subsection @code{byte-compile-file}

@deffn Command byte-compile-file filename &optional load
This function compiles a file of Lisp code named @var{filename} into a
file of bytecode.  The output file's name is made by changing the
@samp{.el} suffix into @samp{.elc}. If @var{filename} does not end in
@samp{.el}, it adds @samp{.elc} to the end of @var{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, 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 @code{t} if there are no errors and @code{nil}
otherwise.  When called interactively, it prompts for the file name.

If @var{load} is non-@code{nil}, this command loads the compiled file
after compiling it.  Interactively, @var{load} is the prefix argument.

@example
@group
$ ls -l push*
-rw-r--r-- 1 lewis lewis 791 Oct  5 20:31 push.el
@end group

@group
(byte-compile-file "~/emacs/push.el")
     @result{} t
@end group

@group
$ ls -l push*
-rw-r--r-- 1 lewis lewis 791 Oct  5 20:31 push.el
-rw-rw-rw- 1 lewis lewis 638 Oct  8 20:25 push.elc
@end group
@end example
@end deffn

@node byte-compile-sexp
@subsection @code{byte-compile-sexp}

@defun byte-compile-sexp sexp

Bytecode compile and return @var{sexp}.

This can be useful for seeing what the byte compile does, especially
when combined with @code{disassemble}.

@example
@group

ELISP> (disassemble
         (byte-compile-sexp '(1+ fill-column)))
byte code:
  args: nil
0	varref	  fill-column
1	add1
2	return
@end group
@end example

@example
@group
ELISP> (disassemble
         (byte-compile-sexp
           '(unwind-protect (1+ fill-column) (ding))))

byte code:
  args: nil
0	constant  <compiled-function>
      args: nil
    0	    constant  ding
    1	    call      0
    2	    return

1	unwind-protect
2	varref	  fill-column
3	add1
4	unbind	  1
5	return
@end group
@end example
@end defun

@node byte-recalc-examples
@subsection @code{byte-recalc-examples}
@deffn Command byte-recalc-examples begin end
This command is what we use in this document to format our examples. It is
not part of Emacs lisp but in @code{byte-pretty.el} inside the repository where
this document lives.

Since we want to show values of various kinds --- offsets, opcodes,
operand, and constant-vector values --- this output is a more verbose than the format
you get from the @code{disassemble} command.
@end deffn


@node byte-recompile-directory
@subsection @code{byte-recompile-directory}

@deffn Command byte-recompile-directory directory &optional flag force
@cindex library compilation
This command recompiles every @samp{.el} file in @var{directory} (or
its subdirectories) that needs recompilation.  A file needs
recompilation if an @samp{.elc} file exists but is older than the
@samp{.el} file.

When a @samp{.el} file has no corresponding @samp{.elc} file,
@var{flag} says what to do.  If it is @code{nil}, this command ignores
these files.  If @var{flag} is 0, it compiles them.  If it is neither
@code{nil} nor 0, it asks the user whether to compile each file,
and asks about each subdirectory as well.

Interactively, @code{byte-recompile-directory} prompts for
@var{directory} and @var{flag} is the prefix argument.

If @var{force} is non-@code{nil}, this command recompiles every
@samp{.el} file that has a @samp{.elc} file.

The returned value is unpredictable.
@end deffn

@node byte-recompile-file
@subsection @code{byte-recompile-file}

@deffn Command byte-recompile-file filename &optional force arg load
@cindex library compilation

Recompile @var{filename} file if it needs recompilation.
This happens when its @samp{.elc} file is older than itself.

If the @samp{.elc} file exists and is up-to-date, normally this function
does not compile @var{filename}.  If the prefix argument @var{force} is non-nil,
however, it compiles @var{filename} even if the destination already
exists and is up-to-date.

If the @samp{.elc} file does not exist, normally this function *does not*
compile @var{filename}.  If optional argument ARG is 0, it compiles
the input file even if the @samp{.elc} file does not exist.
Any other non-nil value of @var{arg} means to ask the user.

If optional argument @var{load} is non-nil, loads the file after compiling.

If compilation is needed, this functions returns the result of
@code{byte-compile-file}; otherwise it returns @var{no-byte-compile}.
@end deffn

@node compile-defun
@subsection @code{compile-defun}
@deffn 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.

@code{compile-defun} normally displays the result of evaluation in the
echo area, but if @var{arg} is non-@code{nil}, it inserts the result
in the current buffer after the form it compiled.
@end deffn

@node disassemble
@subsection @code{disassemble}
@cindex disassembled byte-code

@deffn Command disassemble object &optional buffer-or-name
This command displays the disassembled code for @var{object}.  In
interactive use, or if @var{buffer-or-name} is @code{nil} or omitted,
the output goes in a buffer named @file{*Disassemble*}.  If
@var{buffer-or-name} is non-@code{nil}, it must be a buffer or the
name of an existing buffer.  Then the output goes there, at point, and
point is left before the output.

The argument @var{object} can be a function name, a lambda expression,
or a byte-code object (@pxref{Emacs Lisp Bytecode Objects}).  If it is a lambda
expression, @code{disassemble} compiles it and disassembles the
resulting compiled code.

There are a couple of variables that control how disassembly is displayed:

@multitable  @columnfractions .40 .20
@headitem
Variable Name
@tab
Default Value

@item @code{disassemble-column-1-indent}
@tab  @verb{| 8|}
@item @code{disassemble-column-2-indent}
@tab  @verb{|10|}
@item @code{disassemble-recursive-indent}
@tab  @verb{| 3|}
@end multitable

@end deffn

@node disassemble-file
@subsection @code{disassemble-file}

@deffn Command disassemble-file filename

The command is not part of GNU Emacs, but is included in an
experimental decompiler. It disassembles the entire contents of a bytecode
file using the @code{disassemble-full} for each function.
@end deffn

@node disassemble-full
@subsection @code{disassemble-full}

@deffn Command disassemble object &optional buffer-or-name indent

The command is not part of GNU Emacs, but is included in an
experimental decompiler. In contrast to the standard
@code{disassemble}, the format is slightly modified to make it easier to
decompile the code. For example, the full text of docstring is preserved and is
preceded by a length code of the string.

This functions prints disassembled code for @var{object} in
@var{buffer-or-name}.  @var{object} can be a symbol defined as a
function, or a function itself (a lambda expression or a
compiled-function object).  If @var{object} is not already compiled,
we compile it, but do not redefine @var{object} if it is a symbol."
@end deffn

@node display-call-tree
@subsection @code{display-call-tree}

Even though this is a command, it only has an effect when
@var{byte-compile-generate-call-tree} is set to non-nil; it is
@code{nil} by default. In this case, it is called when a file is byte
compiled, such as from @code{byte-compile-file}.

@deffn Command display-call-tree &optional filename
Display a call graph of a specified file.
This lists which functions have been called, what functions called
them, and what functions they call.  The list includes all functions
whose definitions have been compiled in this Emacs session, as well as
all functions called by those functions.

The call graph does not include macros, inline functions, or
primitives that the byte-code interpreter knows about directly,
e.g. @code{eq}, @code{cons}.

The call tree also lists those functions which are not known to be called
(that is, to which no calls have been compiled), and which cannot be
invoked interactively.
@end deffn

@node emacs-lisp-byte-compile
@subsection @code{emacs-lisp-byte-compile}

Byte compile the file containing the current buffer.  If you want to
do that and also load the file, use
@code{emacs-lisp-byte-compile-and-load}.

@node functionp
@subsection @code{functionp}

This is a general function, regarding functions in general.

@defun functionp object
Non-nil if @var{object} is a function.

Use this to see if a symbol is a function, that is something that can
be called. In most cases though @code{symbol-function} is more useful
as it not only distinguishes functions from non-functions, but can it
returns more information in those situations where @var{object} is a
function.
@end defun


@node make-byte-code
@subsection @code{make-byte-code}

@defun make-byte-code arglist byte-code constants depth &optional docstring interactive-spec &rest elements
Create a byte-code object with specified arguments as elements.
The arguments should be the @var{arglist}, bytecode-string @var{byte-code}, constant
vector @var{constants}, maximum stack size @var{depth}, (optional) @var{docstring},
and (optional) @var{interactive-spec}.

We briefly describe parameters below. For a more detailed discussion
of the parameters, @pxref{Emacs Lisp Bytecode Objects}.

The first four arguments are required; at most six have any
significance.  The @var{arglist} can be either like the one of
‘lambda’, in which case the arguments will be dynamically bound before
executing the bytecode, or it can be an integer of the form
@emph{NNNNNNNRMMMMMMM} where the 7bit @emph{MMMMMMM} specifies the
minimum number of arguments, the 7-bit @emph{NNNNNNN} specifies the
maximum number of arguments (ignoring @b{&rest}) and the @emph{R} bit
specifies whether there is a @b{&rest} argument to catch the left-over
arguments.  If such an integer is used, the arguments will not be
dynamically bound but will be instead pushed on the stack before
executing the byte-code.

There very little checking of the validity of the elements either at
creation time or at run time. If a parameter is are invalid or
inconsistent, Emacs may crash when you call the function.
@end defun

@b{Examples of calling @code{make-byte-code}}:
@findex make-byte-code

@example
@group

;; Null bytecode: no args, no bytecode, no stack needed
ELISP> (make-byte-code nil "" [] 0)

#[nil ""
    []
    0]

;; This byte-code for: '(lambda(a) (* a a ))
ELISP> (make-byte-code '(a) "^H211_\207" [a] 2)

#[(a)
  "^H211_\207"
  [a]
  2]

ELISP> (make-byte-code 1 2 3 4)

#[1 2 3 4]  ;; Doesn't even do type checking!

@end group
@end example

@node symbol-function-fn
@subsection @code{symbol-function}

This is a general function, but it has an interesting use in
conjunction with bytecode.

@defun symbol-function symbol

Return @var{symbol}’s function definition, or nil if that is void.

The value returned from @code{symbol-function} for a function will
when non-nil can be a number of things including:

@itemize
@item
its Lisp expression value (type cons node)
@item
its bytecode value (type compiled-function)
@item
its C function value (type subr)
@item
its Rust function value, if remacs
@item
an autoload function call.
@end itemize

For example if we take a function that is autoloaded when Emacs starts up:
@example
@group
ELISP> (symbol-function 'insert-file)

#[257 "\300^A301\"\207"
      [insert-file-1 insert-file-contents]
      4 2029839 "*fInsert file: "]
@end group
@end example

However if you load a file redefining the function, by loading in
emacs source, you get the last definition:

@example
@group
ELISP> (load-file "/usr/share/emacs/25.2/lisp/files.el.gz")

t
ELISP> (symbol-function 'insert-file)

(closure
  (backup-extract-version-start t)
  (filename)
  "Insert contents of file FILENAME into buffer after point.\nSet mark after the inserted text.\n\nThis function is meant for the user to run interactively.\nDon't call it from programs!  Use `insert-file-contents' instead.\n(Its calling sequence is different; see its documentation)."
  (interactive "*fInsert file: ")
  (insert-file-1 filename #'insert-file-contents))
@end group
@end example

Consider a function that hasn't been is set to be autoloaded:

@example
@group
    ELISP> (symbol-function 'ediff-buffers)

(autoload "ediff" 975154 t nil)
@end group
@end example

Finally, consider an interal function like @code{eolp}
@example
@group
    ELISP> (type-of (symbol-function 'eolp))
subr
@end group
@end example

@end defun