24.1. The System Construction Dictionary
Prev | Chapter 24. System Construction | Next

## 24.1. The System Construction Dictionary [sec_the_syste_n_dictionary]

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 `PATHNAME`s: files to be `LOAD`ed 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 `SIGNAL`ed. 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 `SIGNAL`s 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 standard]
`:COMMON-LISP`
  required by [ANSI CL standard]
`:INTERPRETER`
  `EVAL` is implemented
`:COMPILER`
  `COMPILE` and `COMPILE-FILE` are implemented
`:SOCKETS`
  see Section 32.4, “Socket Streams”
`:GENERIC-STREAMS`
  see Section 31.6, “Generic streams”
`:LOGICAL-PATHNAMES`
  Logical Pathnames are implemented
`:FFI`
  if a foreign function interface (see Section 32.3, “The Foreign Function Call Facility”) is supported (Platform Dependent: Many UNIX, Win32 platforms only)
`:GETTEXT`
  if internationalization (see Section 31.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 31.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`, `:DIRKEY`, `: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.

| These notes document CLISP version 2.45 | Last modified: 2008-04-15

Enter your search termsSubmit search form
Webclisp.cons.orgclisp.podval.orgwww.lisp.org

Prev | Up | Next
Chapter 24. System Construction | Home | Chapter 25. Environment