24.1. The System Construction Dictionary [CLHS-24.2]

24.1. The System Construction Dictionary [CLHS-24.2]
Prev	Chapter 24. System Construction [CLHS-24]	Next

24.1.1. Function COMPILE-FILE
24.1.2. Function COMPILE-FILE-PATHNAME
24.1.3. Function REQUIRE
24.1.4. Function LOAD
24.1.5. Variable *FEATURES*
24.1.6. Function EXT:FEATUREP [CLRFI-1]
24.1.7. Function EXT:COMPILED-FILE-P [CLRFI-2]

The compiler can be called not only by the functions COMPILE, COMPILE-FILE and DISASSEMBLE, but also by the declaration (COMPILE).

24.1.1. Function `COMPILE-FILE`

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*, *COMPILE-VERBOSE*, *COMPILE-PRINT* 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.

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. Function `COMPILE-FILE-PATHNAME`

The default for the :OUTPUT-FILE argument is T, which means #P".fas".

24.1.3. Function `REQUIRE`

The function REQUIRE receives as the optional argument either a PATHNAME or a LIST of PATHNAMEs: files to be LOADed if the required module is not already present.

At compile time, (REQUIRE #P"foo") forms are treated specially: CUSTOM:*LOAD-PATHS* is searched for #P"foo.lisp" and #P"foo.lib". If the latest such file is a #P".lisp", it is compiled; otherwise the #P".lib" is loaded.

The #P".lib" is a “header” file which contains the constant, variable, inline and macro definitions necessary for compilation of the files that REQUIRE this file, but not the function definitions and calls that are not necessary for that. Thus it is not necessary to either enclose REQUIRE forms in EVAL-WHEN or to load the required files in the makefiles: if you have two files, #P"foo.lisp" and #P"bar.lisp", and the latter requires the former, you can write in your Makefile:

all: foo.fas bar.fas

foo.fas: foo.lisp
	clisp -c foo

bar.fas: bar.lisp foo.fas
	clisp -c bar

instead of the more cumbersome (and slower, since #P".lib"s are usually smaller and load faster that #P".fas"s):

bar.fas: bar.lisp foo.fas
        clisp -i foo -c bar

Thus, you do not need to (LOAD #P"foo") in order to (COMPILE-FILE #P"bar.lisp"). If memory is tight, and if #P"foo.lisp" contains only a few inline functions, macros, constants or variables, this is a space and time saver. If #P"foo.lisp" does a lot of initializations or side effects when being loaded, this is important as well.

24.1.4. Function `LOAD`

LOAD accepts four additional keyword arguments :ECHO, :COMPILING, :EXTRA-FILE-TYPES, and :OBSOLETE-ACTION.

(LOAD filename &KEY ((:VERBOSE *LOAD-VERBOSE*) *LOAD-VERBOSE*)
                    ((:PRINT *LOAD-PRINT*) *LOAD-PRINT*)
                    ((:ECHO CUSTOM:*LOAD-ECHO*) CUSTOM:*LOAD-ECHO*) :IF-DOES-NOT-EXIST
                    ((:COMPILING CUSTOM:*LOAD-COMPILING*) CUSTOM:*LOAD-COMPILING*) :EXTRA-FILE-TYPES
                    ((:OBSOLETE-ACTION CUSTOM:*LOAD-OBSOLETE-ACTION*) CUSTOM:*LOAD-OBSOLETE-ACTION*))

:VERBOSE

causes LOAD to emit a short message that a file is being loaded. The default is *LOAD-VERBOSE*, which is initially T, but can be changed by the -v option.

:PRINT

causes LOAD to print the value of each form. The default is *LOAD-PRINT*, which is initially NIL, but can be changed by the -v option.

:ECHO

causes the input from the file to be echoed to *STANDARD-OUTPUT* (normally to the screen). Should there be an error in the file, you can see at one glance where it is. The default is CUSTOM:*LOAD-ECHO*, which is initially NIL, but can be changed by the -v option.

:COMPILING

causes each form read to be compiled on the fly. The compiled code is executed at once and - in contrast to COMPILE-FILE - not written to a file. The default is CUSTOM:*LOAD-COMPILING*, which is initially NIL, but can be changed by the -C option.

:EXTRA-FILE-TYPES

Specifies the LIST of additional file types considered for loading, in addition to CUSTOM:*SOURCE-FILE-TYPES* (which is initially ("lisp" "lsp" "cl")) and CUSTOM:*COMPILED-FILE-TYPES* (which is initially ("fas")).

When filename does not specify a unique file (e.g., filename is #P"foo" and both #P"foo.lisp" and #P"foo.fas" are found in the CUSTOM:*LOAD-PATHS*), then the newest file is loaded.

:OBSOLETE-ACTION

Specifies the action to take when loading a #P".fas" with a different bytecode version from the one supported by this CLISP version. The possible actions are

:DELETE: delete the #P".fas"
:ERROR: SIGNAL an ERROR
:COMPILE: recompile the source file (if present)
NIL (default): WARN and look for another matching file

If no file can be loaded and :IF-DOES-NOT-EXIST is non-NIL, an ERROR is SIGNALed. The default is CUSTOM:*LOAD-OBSOLETE-ACTION*, which is initially NIL.

The variables *LOAD-VERBOSE*, *LOAD-PRINT*, CUSTOM:*LOAD-OBSOLETE-ACTION*, CUSTOM:*LOAD-COMPILING*, and CUSTOM:*LOAD-ECHO* are bound by LOAD when it receives a corresponding keyword argument (:VERBOSE, :PRINT, :OBSOLETE-ACTION, :COMPILING, and :ECHO), i.e., these arguments are recursive, just like the arguments :WARNINGS, :VERBOSE, and :PRINT for COMPILE-FILE.

When evaluation of a read form SIGNALs an ERROR, two RESTART-s are available:

SKIP: Skip this form and read the next one.
STOP: Stop loading the file.

Variable CUSTOM:*LOAD-PATHS*. The variable CUSTOM:*LOAD-PATHS* contains a list of directories where the files are looked for - in addition to the specified or current directory - by LOAD, REQUIRE, COMPILE-FILE and LOAD-LOGICAL-PATHNAME-TRANSLATIONS.

24.1.5. Variable `FEATURES`

The variable *FEATURES* initially contains the following symbols

Default *FEATURES*

:CLISP: the name of this implementation
:ANSI-CL: CLISP purports to conform to [ANSI CL]
:COMMON-LISP: required by [ANSI CL]
:INTERPRETER: EVAL is implemented
:COMPILER: COMPILE and COMPILE-FILE are implemented
:SOCKETS: see Section 31.5, “Socket Streams”
:GENERIC-STREAMS: see Section 30.6, “Generic streams”
:LOGICAL-PATHNAMES: Logical Pathnames are implemented
:FFI: if a foreign function interface (see Section 31.3, “The Foreign Function Call Facility”) is supported (Platform Dependent: Many UNIX, Win32 platforms only)
:GETTEXT: if internationalization (see Section 30.4, “Internationalization of CLISP”) using the GNU gettext package is supported (Platform Dependent: most UNIX platforms only)
:UNICODE: if UNICODE (ISO 10646) characters are supported (see Section 30.5, “Encodings”)
:LOOP: “extended” LOOP form is implemented
:CLOS: CLOS is implemented
:MOP: Meta-Object Protocol is implemented
:WIN32: if hardware = PC (clone) and operating system = Win32 (Windows 95/98/Me/NT/2000/XP)
:PC386: if hardware = PC (clone). It can be used as an indicator for the mainstream hardware characteristics (such as the existence of a graphics card with a non-graphics text mode, or the presence of a keyboard with arrows and Insert/Delete keys, or an ISA/VLB/PCI bus) or software characteristics (such as the Control-Alternate-Delete keyboard combination).
:UNIX: if operating system = UNIX (in this case the hardware is irrelevant!)
:BEOS: if operating system = BeOS (in that case :UNIX is also present)
:CYGWIN: if CLISP is using the Cygwin UNIX compatibility layer on top of Win32 (in that case :UNIX is also present)
:MACOS: if operating system = Mac OS X (in that case :UNIX is also present)

Each module should add the appropriate keyword, e.g., :SYSCALLS, :DIR-KEY, :REGEXP, :PCRE, etc.

24.1.6. Function `EXT:FEATUREP` [CLRFI-1]

(EXT:FEATUREP form) provides run-time access to the read-time conditionals #+ and #-. form is a feature exression.

24.1.7. Function `EXT:COMPILED-FILE-P` [CLRFI-2]

(EXT:COMPILED-FILE-P filename) returns non-NIL when the file filename exists, is readable, and appears to be a CLISP-compiled #P".fas" file compatible with the currently used bytecode format.

System definition facilities (such as asdf or defsystem) can use it to determine whether the file needs to be recompiled.