24.1. Function COMPILE-FILE

24.1. Function `COMPILE-FILE`
Prev	Chapter 24. System Construction chap-24	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 sec_12-1-4-4”), 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.