• Compiler Introduction
• Calling the Compiler
• Compilation Units
  • Undefined Warnings
• Interpreting Error Messages
  • The Parts of the Error Message
  • The Original and Actual Source
  • The Processing Path
  • Error Severity
  • Errors During Macroexpansion
  • Read Errors
  • Error Message Parameterization
• Types in Python
  • Compile Time Type Errors
  • Precise Type Checking
  • Weakened Type Checking
• Getting Existing Programs to Run
• Compiler Policy
  • The Optimize Declaration
  • The Optimize-Interface Declaration
• Open Coding and Inline Expansion

• Source level debugging of compiled code (see chapter 3.)
  
  
• Type error compiler warnings for type errors detectable at compile time.
  
  
• Compiler error messages that provide a good indication of where the error appeared in the source.
  
  
• Full run-time checking of all potential type errors, with optimization of type checks to minimize the cost.
  
  
• Scheme-like features such as proper tail recursion and extensive source-level optimization.
  
  
• Advanced tuning and optimization features such as comprehensive efficiency notes, flow analysis, and untagged number representations (see chapter 5.)

This function compiles the function whose name is name. If name is nil, the compiled function object is returned. If definition is supplied, it should be a lambda expression that is to be compiled and then placed in the function cell of name. As per the proposed X3J13 cleanup ``compile-argument-problems'', definition may also be an interpreted function.

The return values are as per the proposed X3J13 cleanup ``compiler-diagnostics''. The first value is the function name or function object. The second value is nil if no compiler diagnostics were issued, and t otherwise. The third value is nil if no compiler diagnostics other than style warnings were issued. A non-nil value indicates that there were ``serious'' compiler diagnostics issued, or that other conditions of type error or warning (but not style-warning) were signaled during compilation.

The CMUCL compile-file is extended through the addition of several new keywords and an additional interpretation of input-pathname:

input-pathname

If this argument is a list of input files, rather than a single input pathname, then all the source files are compiled into a single object file. In this case, the name of the first file is used to determine the default output file names. This is especially useful in combination with block-compile.

:output-file

This argument specifies the name of the output file. t gives the default name, nil suppresses the output file.

:error-file

A listing of all the error output is directed to this file. If there are no errors, then no error file is produced (and any existing error file is deleted.) t gives "name.err" (the default), and nil suppresses the output file.

:error-output

If t (the default), then error output is sent to *error-output*. If a stream, then output is sent to that stream instead. If nil, then error output is suppressed. Note that this error output is in addition to (but the same as) the output placed in the error-file.

:verbose

If t (the default), then the compiler prints to error output at the start and end of compilation of each file. See *compile-verbose*.

:print

If t (the default), then the compiler prints to error output when each function is compiled. See *compile-print*.

:progress

If t (default nil), then the compiler prints to error output progress information about the phases of compilation of each function. This is a CMUCL extension that is useful mainly in large block compilations. See *compile-progress*.

:trace-file

If t, several of the intermediate representations (including annotated assembly code) are dumped out to this file. t gives "name.trace". Trace output is off by default. See section 5.12.5.

:load

If t, load the resulting output file.

:block-compile

Controls the compile-time resolution of function calls. By default, only self-recursive calls are resolved, unless an ext:block-start declaration appears in the source file. See section 5.7.3.

:entry-points

If non-nil, then this is a list of the names of all functions in the file that should have global definitions installed (because they are referenced in other files.) See section 5.7.3.

:byte-compile

If t, compiling to a compact interpreted byte code is enabled. Possible values are t, nil, and :maybe (the default.) See *byte-compile-default* and see section 5.9.

:xref

If non-nil, enable recording of cross-reference information. The default is the value of c:*record-xref-info*. See section 12. Note that the compiled fasl file will also contain cross-reference information and loading the fasl later will populate the cross-reference database.

The return values are as per the proposed X3J13 cleanup ``compiler-diagnostics''. The first value from compile-file is the truename of the output file, or nil if the file could not be created. The interpretation of the second and third values is described above for compile.

[Variable]
*compile-print*    

[Variable]
*compile-progress*    

These variables determine the default values for the :verbose, :print and :progress arguments to compile-file.

This function is similar to compile-file, but it takes all its arguments as streams. It reads Common Lisp code from input-stream until end of file is reached, compiling into the current environment. This function returns the same two values as the last two values of compile. No output files are produced.

This macro evaluates the forms in an environment that causes warnings for undefined variables, functions and types to be delayed until all the forms have been evaluated. Each keyword value is an evaluated form. These keyword options are recognized:

:override

If uses of with-compilation-unit are dynamically nested, the outermost use will take precedence, suppressing printing of undefined warnings by inner uses. However, when the override option is true this shadowing is inhibited; an inner use will print summary warnings for the compilations within the inner scope.

:optimize

This is a CMUCL extension that specifies of the ``global'' compilation policy for the dynamic extent of the body. The argument should evaluate to an optimize declare form, like:

      (optimize (speed 3) (safety 0))
    

See section 4.7.1

:optimize-interface

Similar to :optimize, but specifies the compilation policy for function interfaces (argument count and type checking) for the dynamic extent of the body. See section 4.7.2.

:context-declarations

This is a CMUCL extension that pattern-matches on function names, automatically splicing in any appropriate declarations at the head of the function definition. See section 5.7.5.

(with-compilation-unit ()
  (compile-file "file1")
  (compile-file "file2")
  ...)

This variable controls the number of undefined warnings for each distinct name that are printed with full source context when the compilation unit ends. If there are more undefined references than this, then they are condensed into a single warning:

    Warning: count more uses of undefined function name.
  

When the value is 0, then the undefined warnings are not broken down by name at all: only the summary listing of undefined names is printed.

(defmacro zoq (x)
  `(roq (ploq (+ ,x 3))))

(defun foo (y)
  (declare (symbol y))
  (zoq y))

File: /usr/me/stuff.lisp
In: DEFUN FOO
  (ZOQ Y)
--> ROQ PLOQ + 
==>
  Y
Warning: Result is a SYMBOL, not a NUMBER.

File: /usr/me/stuff.lisp

This is the file that the compiler read the relevant code from. The file name is displayed because it may not be immediately obvious when there is an error during compilation of a large system, especially when with-compilation-unit is used to delay undefined warnings.

In: DEFUN FOO

This is the definition or top-level form responsible for the error. It is obtained by taking the first two elements of the enclosing form whose first element is a symbol beginning with ``DEF''. If there is no enclosing defmumble, then the outermost form is used. If there are multiple defmumbles, then they are all printed from the out in, separated by =>'s. In this example, the problem was in the defun for foo.

(ZOQ Y)

This is the original source form responsible for the error. Original source means that the form directly appeared in the original input to the compiler, i.e. in the lambda passed to compile or the top-level form read from the source file. In this example, the expansion of the zoq macro was responsible for the error.

--> ROQ PLOQ +

This is the processing path that the compiler used to produce the errorful code. The processing path is a representation of the evaluated forms enclosing the actual source that the compiler encountered when processing the original source. The path is the first element of each form, or the form itself if the form is not a list. These forms result from the expansion of macros or source-to-source transformation done by the compiler. In this example, the enclosing evaluated forms are the calls to roq, ploq and +. These calls resulted from the expansion of the zoq macro.

==> Y

This is the actual source responsible for the error. If the actual source appears in the explanation, then we print the next enclosing evaluated form, instead of printing the actual source twice. (This is the form that would otherwise have been the last form of the processing path.) In this example, the problem is with the evaluation of the reference to the variable y.

Warning: Result is a SYMBOL, not a NUMBER.

This is the explanation the problem. In this example, the problem is that y evaluates to a symbol, but is in a context where a number is required (the argument to +).

• File: and In: mark the file and definition, respectively.
  
  
• The original source is an indented form with no prefix.
  
  
• Each line of the processing path is prefixed with -->.
  
  
• The actual source form is indented like the original source, but is marked by a preceding ==> line. This is like the ``macroexpands to'' notation used in Common Lisp: The Language.
  
  
• The explanation is prefixed with the error severity (see section 4.4.4), either Error:, Warning:, or Note:.

File: /usr/me/stuff.lisp
In: DEFUN FOO
  (ZOQ Y)
--> ROQ 
==>
  (PLOQ (+ Y 3))
Warning: Undefined function: PLOQ

==>
  (ROQ (PLOQ (+ Y 3)))
Warning: Undefined function: ROQ

[Last message occurs repeats times]

(defun bar (x)
  (let (a)
    (declare (fixnum a))
    (setq a (foo x))
    a))

In: DEFUN BAR
  (LET (A) (DECLARE (FIXNUM A)) (SETQ A (FOO X)) A)
Warning: The binding of A is not a FIXNUM:
  NIL

(defun foo (n)
  (dotimes (i n *undefined*)))

In: DEFUN FOO
  (DOTIMES (I N *UNDEFINED*))
--> DO BLOCK LET TAGBODY RETURN-FROM 
==>
  (PROGN *UNDEFINED*)
Warning: Undefined variable: *UNDEFINED*

(do ((i 0 (1+ i)) (#:g1 n))
    ((>= i #:g1) *undefined*)
  (declare (type unsigned-byte i)))

(block nil
  (let ((i 0) (#:g1 n))
    (declare (type unsigned-byte i))
    (tagbody (go #:g3)
     #:g2    (psetq i (1+ i))
     #:g3    (unless (>= i #:g1) (go #:g2))
             (return-from nil (progn *undefined*)))))

Error

This severity is used when the compiler encounters a problem serious enough to prevent normal processing of a form. Instead of compiling the form, the compiler compiles a call to error. Errors are used mainly for signaling syntax errors. If an error happens during macroexpansion, the compiler will handle it. The compiler also handles and attempts to proceed from read errors.

Warning

Warnings are used when the compiler can prove that something bad will happen if a portion of the program is executed, but the compiler can proceed by compiling code that signals an error at runtime if the problem has not been fixed:

• Violation of type declarations, or
  
  
• Function calls that have the wrong number of arguments or malformed keyword argument lists, or
  
  
• Referencing a variable declared ignore, or unrecognized declaration specifiers.

In the language of the Common Lisp standard, these are situations where the compiler can determine that a situation with undefined consequences or that would cause an error to be signaled would result at runtime.

Note

Notes are used when there is something that seems a bit odd, but that might reasonably appear in correct programs.

(defun foo (e l)
  (do ((current l (cdr current))
       ((atom current) nil))
      (when (eq (car current) e) (return current))))

In: DEFUN FOO
  (DO ((CURRENT L #) (# NIL)) (WHEN (EQ # E) (RETURN CURRENT)) )
Error: (during macroexpansion)

Error in function LISP::DO-DO-BODY.
DO step variable is not a symbol: (ATOM CURRENT)

Error: Read error at 2:
 "(,/\foo)"
Error in function LISP::COMMA-MACRO.
Comma not inside a backquote.

M-< C-u position C-f

Error: Read error in form starting at 14:
 "(defun test ()"
Error in function LISP::FLUSH-WHITESPACE.
EOF while reading #<Stream for file "/usr/me/test.lisp">

This variable specifies the number of enclosing actual source forms that are printed in full, rather than in the abbreviated processing path format. Increasing the value from its default of 1 allows you to see more of the guts of the macroexpanded source, which is useful when debugging macros.

[Variable]
*error-print-level*    

These variables are the print level and print length used in printing error messages. The default values are 5 and 3. If null, the global values of *print-level* and *print-length* are used.

This macro defines how to extract an abbreviated source context from the named form when it appears in the compiler input. lambda-list is a defmacro style lambda-list used to parse the arguments. The body should return a list of subforms that can be printed on about one line. There are predefined methods for defstruct, defmethod, etc. If no method is defined, then the first two subforms are returned. Note that this facility implicitly determines the string name associated with anonymous functions.

• Python treats type declarations much differently that other Lisp compilers do. Python doesn't blindly believe type declarations; it considers them assertions about the program that should be checked.
  
  
• Python also has a tremendously greater knowledge of the Common Lisp type system than other compilers. Support is incomplete only for the not, and and satisfies types.

(defun raz (foo)
  (let ((x (case foo
             (:this 13)
             (:that 9)
             (:the-other 42))))
    (declare (fixnum x))
    (foo x)))

In: DEFUN RAZ
  (CASE FOO (:THIS 13) (:THAT 9) (:THE-OTHER 42))
--> LET COND IF COND IF COND IF 
==>
  (COND)
Warning: This is not a FIXNUM:
  NIL

This function can be used as the default value for keyword arguments that must always be supplied. Since it is known by the compiler to never return, it will avoid any compile-time type warnings that would result from a default value inconsistent with the declared type. When this function is called, it signals an error indicating that a required keyword argument was not supplied. This function is also useful for defstruct slot defaults corresponding to required arguments. See section 5.2.5.

Although this function is a CMUCL extension, it is relatively harmless to use it in otherwise portable code, since you can easily define it yourself:

    (defun required-argument ()
      (error "A required keyword argument was not supplied."))
    

(or node hunk (member :foo :bar :baz))

(defstruct foo
  (a nil :type simple-string))

(defstruct bar
  (a nil :type single-float))

(defun myfun (x)
  (declare (type bar x))
  (* (bar-a x) 3.0))

Type-error in MYFUN:
  NIL is not of type BAR

Type-error in MYFUN:
  NIL is not of type STRUCTURE

(prog (foo)
  (declare (fixnum foo))
  (setq foo ...)
  ...)

(prog (foo)
  (declare (type (or fixnum null) foo))
  (setq foo ...)
  ...)

(prog ((foo 0))
  (declare (fixnum foo))
  (setq foo ...)
  ...)

(defmacro my-1+ (x)
  (declare (fixnum x))
  `(the fixnum (1+ ,x)))

(my-1+ (+ 4 5))

(defmacro my-1+ (x)
  `(the fixnum (1+ (the fixnum ,x))))

(do ((pos 0 (position #\a string :start (1+ pos))))
    ((null pos))
  (declare (fixnum pos))
  ...)

(do ((pos 0 (position #\a string :start (1+ pos))))
    ((null pos))
  (let ((pos pos))
    (declare (fixnum pos))
    ...))

speed

How fast the program should is run. speed 3 enables some optimizations that hurt debuggability.

compilation-speed

How fast the compiler should run. Note that increasing this above safety weakens type checking.

space

How much space the compiled code should take up. Inline expansion is mostly inhibited when space is greater than speed. A value of 0 enables promiscuous inline expansion. Wide use of a 0 value is not recommended, as it may waste so much space that run time is slowed. See section 5.8 for a discussion of inline expansion.

debug

How debuggable the program should be. The quality is treated differently from the other qualities: each value indicates a particular level of debugger information; it is not compared with the other qualities. See section 3.6 for more details.

safety

How much error checking should be done. If speed, space or compilation-speed is more important than safety, then type checking is weakened (see section 4.5.3). If safety if 0, then no run time error checking is done. In addition to suppressing type checks, 0 also suppresses argument count checking, unbound-symbol checking and array bounds checks.

extensions:inhibit-warnings

This is a CMUCL extension that determines how little (or how much) diagnostic output should be printed during compilation. This quality is compared to other qualities to determine whether to print style notes and warnings concerning those qualities. If speed is greater than inhibit-warnings, then notes about how to improve speed will be printed, etc. The default value is 1, so raising the value for any standard quality above its default enables notes for that quality. If inhibit-warnings is 3, then all notes and most non-serious warnings are inhibited. This is useful with declare to suppress warnings about unavoidable problems.

• Attempts to redefine standard functions may be frustrated, since the function may never be called. Although it is technically illegal to redefine standard functions, users sometimes want to implicitly redefine these functions when they are debugging using the trace macro. Special-casing of standard functions can be inhibited using the notinline declaration.
  
  
• The compiler can have multiple alternate implementations of standard functions that implement different trade-offs of speed, space and safety. This selection is based on the compiler policy, see section 4.7.

(nthcdr 4 foobar)

(cdr (cdr (cdr (cdr foobar))))

(do ((i 0 (1+ i))
     (list foobar (cdr foobar)))
    ((= i 4) list))

(nth x l)

(car (nthcdr x l))

1

There are a few circumstances where a type declaration is discarded rather than being used as type assertion. This doesn't affect safety much, since such discarded declarations are also not believed to be true by the compiler.

2

The initial value need not be of this type as long as the corresponding argument to the constructor is always supplied, but this will cause a compile-time type warning unless required-argument is used.

3

Actually, this declaration is totally unnecessary in Python, since it already knows position returns a non-negative fixnum or nil.

4

See the proposed X3J13 ``lisp-symbol-redefinition'' cleanup.