All Manuals > LispWorks User Guide and Reference Manual > 33 The COMMON-LISP Package

NextPrevUpTopContentsIndex

compile-file

Function
Summary

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

Package

common-lisp

Signature

compile-file input-file &key output-file verbose print external-format load => output-truename, warnings-p, failure-p

Arguments

input-file

A pathname designator.

output-file

A pathname designator, or :temp.

verbose

A generalized boolean.

print

A generalized boolean.

external-format

An external format specification.

load

A generalized boolean or the keyword :delete.

Values

output-truename

A pathname or nil.

warnings-p

A generalized boolean.

failure-p

A generalized boolean.

Description

The function 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 .*fasl extension (the actual extension depends on the host machine CPU and the LispWorks implementation). 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 loading has the desired effect. In particular objects need to have space allocated for them, and top level forms are called as they are loaded.

output-file specifies the location of the output file, relative to the current directory (not the path of the file). If it specifies a directory, then the output file is placed there instead of the same directory as the source. If it contains a file name but not a file type, then the platform specific file type is added and the result specifies the full path of the output file. If output-file has a type, it specifies the full path of the output file. Note that in this case when you want to load the file you will need to add the type to *binary-file-types*. See the example below.

The special value output-file :temp offers a convenient way to specify that the output file is a temporary file in a location that is likely to be writable.

verbose controls the printing of messages describing the file being compiled, the current optimization settings, and other information. If verbose is nil, there are no messages. If verbose is 0, only the "Compiling file..." message is printed. For all other true values of verbose, messages are also printed about:

The default value is the value of *compile-verbose*, which defaults to t.

print controls the printing of information about the compilation. It can have the following values. If print is nil, no information is printed. If print is a non-positive number, then only warnings are printed. If print is a positive number no greater than 1, or if print is any non-number object, then the information printed consists of all warning messages and one line of information per function that is compiled. If print is a number greater than 1, then full information is printed. The default value of print is the value of *compile-print*, which has the default value 1.

Warning messages are printed to *error-output*. Other messages are printed to *standard-output*.

external-format is interpreted as for open. The default value is :default.

If load is true, then the file is loaded after compilation. If load is the special value :delete then the compiled file is deleted after loading it. The source file is not affected. This is especially useful when using output-file :temp, to avoid leaving compiled files.

output-truename is the truename of the output file, or nil if that cannot be created.

warnings-p is nil if no conditions of type error or warning were detected during compilation. Otherwise warnings-p is a list containing the conditions.

failure-p is nil if no conditions of type error or warning (other than style-warning) were detected by the compiler, and t otherwise.

Compatibility notes

In LispWorks 5.1 and previous versions, warning messages are printed to *standard-output*.

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 of a file foo.lisp (on an Intel Macintosh, for example) a temporary output file named t_foo.xfasl is used, so that an unsuccessful compile does not overwrite an existing foo.xfasl.

LispWorks uses the following naming conventions for fasl files, and it is recommended that you should use them too, to ensure correct operation of load and so on.

Naming conventions for FASL files

Machine/Implementation

Fasl Extension

x86 Windows/32-bit LispWorks

.ofasl

x64 Windows/64-bit LispWorks

.64ofasl

x86 Linux/32-bit LispWorks

.ufasl

amd64 Linux/64-bit LispWorks

.64ufasl

ARM Linux/32-bit LispWorks

.rfasl

x86 FreeBSD/32-bit LispWorks

.ffasl

amd64 FreeBSD/64-bit LispWorks

.64ffasl

AIX PowerPC/32-bit LispWorks

.ifasl

AIX PowerPC/64-bit LispWorks

.64ifasl

SPARC/32-bit LispWorks

.wfasl

SPARC/64-bit LispWorks

.64wfasl

x86 Solaris/32-bit LispWorks

.sfasl

amd64 Solaris/64-bit LispWorks

.64sfasl

Intel Macintosh/32-bit LispWorks

.xfasl

Intel Macintosh/64-bit LispWorks

.64xfasl

LispWorks for iOS Runtime simulator

.xcfasl

LispWorks for iOS Runtime

.rfasl

LispWorks for Android Runtime

.rfasl

You can find the fasl file extension appropriate for your machine by looking at the variable *binary-file-type*. The variable *binary-file-types* contains a list of all the file extensions currently recognized by load, require and load-data-file (in addition to *binary-file-type*).

Compatibility notes
  1. In LispWorks for Windows 4.4 and previous versions, the fasl file extension is .fsl. This changed in LispWorks 5.0.
  2. In LispWorks for Linux 4.4 and previous versions, the fasl file extension is .ufsl. This changed in LispWorks 5.0.
See also

compile
compile-file-if-needed
*compiler-break-on-error*
disassemble


LispWorks User Guide and Reference Manual - 13 Feb 2015

NextPrevUpTopContentsIndex