Function

Summary

Compile a Lisp source file into a form that both loads and runs faster.

Package

common-lisp

Signature

compile-file pathname &key load output-file print verbose => pathname

Arguments

load

If t , the file is loaded after compilation.

output-file

Specifies the location of the output file. This keyword is useful if you are using a different file-extension for binary files. If you use different file-extensions for binary files, you must inform LispWorks of this by pushing the file-extension string onto the variable sys::*binary-file-types* . If you fail to do this, LispWorks assumes that these files are text rather than compiled files. See the example below.

print

This argument controls the printing of information about the compilation. It can have the following values:

nil -- No information is printed.

2 -- Full information is printed out.

1 -- The information printed out consists of all warning messages and one line of information per function that is compiled.

0 -- Only warning messages are printed.

− 1 -- Nothing at all is printed out.

If this argument has any other value, the level 1 information is printed. The default value for :print is *compile-print* , which has the default value 1.

verbose

Controls the printing of messages about the current optimization settings. If verbose is 0 , only the "Compiling file..." message is printed. The default value is *compile-verbose* , which defaults to t .

Values

A single value is returned, being the pathname argument supplied, or nil if the compile was unsuccessful

Description

compile-file calls the compiler to translate a Lisp source file into a form that both loads and runs faster. A compiled function typically runs more than ten times faster than when interpreted (assuming that it is not spending most of its work calling already compiled functions). A source file with a .lisp or .lsp extension compiles to produce a file with a .*x*fasl extension (the actual extension depends on the host machine CPU). Subsequent use of load loads the compiled version (which is in LispWorks's FASL or Fast Load format) in preference to the source.

In compiling a file the compiler has to both compile each function and top level form in the file, and to produce the appropriate FASL directives so that load ing has the desired effect. In particular objects need to have space allocated for them, and top level forms are called as they are loaded.

Examples

(compile-file "devel/fred.lisp")

     ;; compile fred.lisp to fred.fasl

(compile-file "devel/fred") 

     ;; does the same thing

(compile-file "test" :load t) 

     ;; compile test.lisp, then load if successful

(compile-file "program" :output-file "program.abc")

     ;; compile  "program.lisp" to "program.abc"

(push "abc" sys::*binary-file-types*)

     ;; tells LispWorks that files with extension

     ;; ".abc" are binaries

Notes

See declare for a list of the declarations that alter the behavior of the compiler.

The act of compiling a file should have no side effects, other than the creation of symbols and packages as the input file is read by the reader.

By default a form is skipped if an error occurs during compilation. If you need to debug an error during compilation by compile-file , set *compiler-break-on-error* .

During compilation an output file with an extension of .fasl_t is used, so that an unsuccessful compile does not overwrite an existing .fasl .

The actual extensions used vary according to machine type. See under with-output-to-fasl-file for a full list of FASL file extensions.

See also

compile

*compiler-break-on-error*

disassemble