24.1. Function COMPILE-FILE

24.1. Function `COMPILE-FILE`
Prev	Chapter 24. System Construction	Next

24.1. Function `COMPILE-FILE`

24.1.1. Output files
24.1.2. Return values

COMPILE-FILE compiles a file to a platform-independent bytecode:

(COMPILE-FILE filename &KEY :OUTPUT-FILE :LISTING :EXTERNAL-FORMAT
                            ((:WARNINGS CUSTOM:*COMPILE-WARNINGS*) CUSTOM:*COMPILE-WARNINGS*)
                            ((:VERBOSE *COMPILE-VERBOSE*) *COMPILE-VERBOSE*)
                            ((:PRINT *COMPILE-PRINT*) *COMPILE-PRINT*))

Options for COMPILE-FILE

filename: the file to be compiled, should be a pathname designator.
:OUTPUT-FILE: should be NIL or T or a pathname designator or an output STREAM. The default is T.
:LISTING: should be NIL or T or a pathname designator or an output STREAM. The default is NIL.
:EXTERNAL-FORMAT: the EXT:ENCODING of the filename.
:WARNINGS: specifies whether warnings should also appear on the screen.
:VERBOSE: specifies whether error messages should also appear on the screen.
:PRINT: specifies whether an indication which forms are being compiled should appear on the screen.

The variables CUSTOM:*COMPILE-WARNINGS* (initially set to T), *COMPILE-VERBOSE* (initially set to T, affected by -v) *COMPILE-PRINT* (initially set to NIL, affected by -v) provide defaults for the :WARNINGS, :VERBOSE, :PRINT keyword arguments, respectively, and are bound by COMPILE-FILE to the values of the arguments, i.e., these arguments are recursive.

24.1.1. Output files

For each input file (default file type: #P".lisp") the following files are generated:

File	When	Default file type	Contents
output file	only if `:OUTPUT-FILE` is not `NIL`	`#P".fas"`	can be loaded using the `LOAD` function
auxiliary output file	only if `:OUTPUT-FILE` is not `NIL`	`#P".lib"`	used by `COMPILE-FILE` when compiling a `REQUIRE` form referring to the input file
listing file	only if `:LISTING` is not `NIL`	`#P".lis"`	disassembly of the output file
C output file	only if `:OUTPUT-FILE` is not `NIL`	`#P".c"`	“FFI”; this file is created only if the source contains “FFI” forms

Warning

If you have two files in the same directory - #P"foo.lisp" and #P"foo.c", and you compile the first file with CLISP, the second file will be clobbered if you have any “FFI” forms in the first one!

24.1.2. Return values

As per [ANSI CL standard], COMPILE-FILE returns 3 values:

output-truename: the truename of the output #P".fas", or NIL if the file could not be created, in which case the compilation is considered to have failed
warnings-p: NIL if no conditions of type ERROR or WARNING were detected during compilation, and the number of such conditions otherwise
failure-p: NIL if no conditions of type ERROR or WARNING (other than STYLE-WARNING) were detected during compilation, and the number of such conditions otherwise

Since CLISP tends to be relatively garrulous with warnings (see, e.g., Section 12.2.4.1, “Rule of Float Precision Contagion ”), the non-NIL tertiary return value (called failure-p by the [ANSI CL standard]) does not indicate a failure of compilation. The correct way to check whether COMPILE-FILE has failed is the primary return value.