6 Compiling Lisp Programs

6.2 Reference pages

Syntax:compile function-or-method&optional function-definition&rest compiler-options

The functioncompile compiles an interpreted function or method in the current Lisp environment and replaces the interpreted function or method definition with the compiled version. For interpreted functions,compile produces a compiled function object from a lambda expression. The lambda expression is the argument function-definition if it is present; otherwise, the function definition of the symbol function-or-method is the relevant lambda expression.

The function-or-method argument tocompile specifies a function name, a method object, or the name of a method to be compiled.

If the function-or-method argument is a function name, the function definition of the symbol function-or-method is set to the compiled function object, andcompile returns that symbol. If the function-or-method argument isnil and the optional function-definition argument is supplied,compile returns the function object.

If the function-or-method argument is a method object or a method name,compile compiles the specified method and returns the method name.

A method name has the following form:

(method generic-function-name{qualifiers}*({specializer-name}*))

The compiler-options arguments can be any of the keyword-value pairs supplied to the functioncompiler-options. These keyword arguments affect only the specified compilation.

> (defun double (x) (+ x x))
DOUBLE

> (compile 'double)
DOUBLE

> (double 2)
4

> (funcall (compile nil '(lambda (x) (+ x x))) 3)
6

;;; Define the method ADD-ONE and create its associated
;;; generic function.
> (defmethod add-one ((x number)) (+ x 1))
#<Standard-Method ADD-ONE (NUMBER)>

> (compile '(method add-one (number)))
(METHOD ADD-ONE (NUMBER))

> (add-one 5)
6

See Also: compile-file, compiler-options, uncompile

Syntax:compile-file input-pathname &key :output-file &rest compiler-options

The functioncompile-file produces binary files from Lisp source files. The compiled functions contained in the binary files become available for use when the binary files are loaded into Lisp.

The function converts the code in the file specified by the input-pathname argument into compiled code. It searches for the source file as follows:

• If the input-pathname argument is a pathname that is not fully specified, default values are taken from the value of the Common Lisp variable*default-pathname-defaults* by using the Common Lisp functionmerge-pathnames.

• If the input-pathname argument specifies a pathname that has an explicit type component,compile-file searches for a file that matches the given pathname.

• If the input-pathname argument specifies a pathname that does not have an explicit type component,compile-file searches for source files by merging successive elements of*load-source-pathname-types* with the given pathname until it finds a match. If a source file does not exist,compile-file signals a continuable error and prompts for a new filename.

The:output-file keyword argument controls where the compiled code is written. If this argument is not specified or if its value isnil, the name of the output file is the pathname specified by the input-pathname argument with the following exception: the type component is taken from the first element of the list stored in the variable*load-binary-pathname-types*; the initial value of this element is.bin.

If this keyword argument is specified, its argument should be a pathname or a string describing a valid filename. If the specified pathname does not include a type component, the type component is taken from the first element of the variable*load-binary-pathname-types*.

The default value of:output-file isnil.

Thecompiler-options arguments can be any of the keyword-value pairs supplied to the functioncompiler-options. These keyword arguments affect only the specified compilation. The keyword arguments are extensions to Common Lisp.

See Also: compile, compiler-options; load, *load-binary-pathname-types*, *load-source-pathname-types* (in The Advanced User's Guide)

Syntax:compiled-function-p object

The predicatecompiled-function-p is true if its argument is a compiled function object; otherwise, it is false.

> (compiled-function-p (symbol-function 'append))
T

> (compiled-function-p #'(lambda (x) x))
NIL

Syntax:compiler-options &key :messages :file-messages :optimize-message :warnings :undef-warnings :show-optimizations :fast-entry :write-safety :read-safety :tail-merge :notinline :egc

The functioncompiler-options sets the default values of the keyword arguments to the functionscompile andcompile-file.

You can specify the following keyword arguments tocompiler-options:

• :messages

This keyword argument controls Compiler messages. A value oft sends messages to the standard output stream; otherwise, the value must specify a stream to which messages can be sent. The initial value isnil, which suppresses Compiler messages.

• :file-messages

This keyword argument controls Compiler file messages. These messages include"Reading source file...","Writing binary file...", and messages that give the current settings forspeed,safety,space, andcompilation-speed. A value ofnil means issue no file messages; otherwise, the value should specify a stream to which messages can be sent. The initial value ist, which sends the messages to the standard output stream.

• :optimize-message

This keyword argument controls optimization mode messages, which tell you whether you are using the production mode or the development mode of the Compiler. A value ofnil suppresses mode messages. A value of:terse allows terse messages. The initial value ist, which allows full optimization mode messages.

• :warnings

This keyword argument controls the warnings issued by the Compiler. A value ofnil means issue no warnings; otherwise, the value must be eithert or a stream to which warnings can be sent. The initial value ist, which sends the warnings to the stream that is the value of the Common Lisp variable*error-output*.

• :undef-warnings

This keyword argument controls the Compiler warnings about undefined function references. A value ofnil suppresses warnings. The initial value ist.

• :show-optimizations

This keyword argument controls optimization reporting, which indicates the success or failure of optimization attempts. A non-nil value shows optimization reports. The value:failure-only causes the Compiler to report only those optimizations that failed. The initial value isnil.

• :fast-entry

For LCL/SGI, this keyword argument has no effect, since argument checking does not increase the time required to perform a function call. On other platforms, this keyword argument controls checking the number of arguments on entry to a function with a fixed number of arguments. A non-nil value means the Compiler does not insert checking in the compiled code. Calls to functions compiled in this manner are slightly faster. Settingsafety to 0 has the same effect on fast entry as setting:fast-entry tot. The initial value of:fast-entry isnil.

• :write-safety

This keyword argument controls checking for write-access operations. A non-nil value means the Compiler adds checking. Settingsafety to 2 has the same effect on write access as setting:write-safety tot. The initial value of:write-safety ist.

• :read-safety

This keyword argument controls checking for read-access operations. A non-nil value means the Compiler adds checking. Settingsafety to 3 has the same effect on read access as setting:read-safety tot. The initial value of:read-safety ist.

• :tail-merge

This keyword argument controls tail merging. A non-nil value causes the Compiler to convert tail-recursive calls to iterative constructions and to perform other types of tail call optimizations, such as tail merging, that eliminate the overhead of some function calls. Settingspeed to 3 has the same effect on tail merging as setting:tail-merge tot. The initial value of:tail-merge isnil.

• :notinline

If this keyword argument has a non-nil value, the Compiler behaves as if all functions have been declarednotinline; the compiled code uses procedure calls to functions rather than the machine-language code for the functions. Settingspeed to 0 has the same effect on in-line calls as setting:notinline tot. The initial value of:notinline isnil.

• :egc

If this keyword argument has a non-nil value, the Compiler produces code that can be executed when ephemeral garbage collection is on. If the value isnil, the Compiler produces code that is incompatible with ephemeral garbage collection. Attempting to run such code when ephemeral garbage collection is already turned on signals a continuable error. The initial value of:egc ist. See Chapter 5, "Storage Management in Common Lisp" for more information about ephemeral garbage collection.

LCL/SGI takes an additional keyword argument,:target.

• :target

This keyword argument causes the Compiler to generate code for a specific type of MIPS processor. It can have one of the following values:

• mips-little-endian

This value causes the Compiler to generate binary files that run only on machines with little-endian byte ordering.

• mips-big-endian

This value causes the Compiler to generate binary files that run only on machines with big-endian byte ordering. This is the initial value of the:target option.

• mips

This value causes the Compiler to generate binary code that can run on machines with either little-endian or big-endian byte ordering. Binary files produced with this target can be loaded into either machine type. Certain operations, such as accessing floating-point arrays, will run more slowly.

See Also: compile, compile-file

Syntax:disassemble name-or-compiled-function

The functiondisassemble disassembles a compiled function and prints the resulting code on the standard output. It returnsnil.

If the argument is the name of an interpreted function, that function is first compiled and then disassembled. The function definition that is attached to the name as the content of the symbol's function cell is not changed.

The standard output is defined by the value of the Common Lisp variable*standard-output*.

Syntax:eval-when ({situation}*) {form}*

The special formeval-when specifies when a particular body of code will be executed.

The execution time is defined by the situation arguments. Each argument must have one of the following values:

• If the value iseval, the evaluator evaluates the form arguments at execution time.

• If the value iscompile, the Compiler evaluates the form arguments at compilation time.

• If the value isload and the file containing theeval-when is compiled, then the forms are compiled; they are executed when the output file produced by the Compiler is loaded.

The value of the last form evaluated is returned as the result ofeval-when. If no forms are executed,eval-when returnsnil.

The form arguments are executed in order.

> (setq test 3)
3

> (eval-when (compile) (setq test 2))
NIL

> test
3

> (eval-when (eval) (setq test 2))
2

> test
2

Syntax:uncompile name

The functionuncompile replaces the compiled version of the specified function or macro with its original interpreted definition. The function or macro must have been compiled by a call to the functioncompile; otherwise, an error is signaled.

See Also: compile

Generated with Harlequin WebMaker