Skip to main content

with-compilation-unit

with-compilation-unit Macro

Syntax:

with-compilation-unit ([[ ↓option ]]) {form}* → {result}*

option::=:override override

Arguments and Values:

override—a generalized boolean; evaluated. The default is nil.

forms—an implicit progn.

results—the values returned by the forms.

Description:

Executes forms from left to right. Within the dynamic environment of with-compilation-unit, actions deferred by the compiler until the end of compilation will be deferred until the end of the outermost call to with-compilation-unit.

The set of options permitted may be extended by the implementation, but the only standardized keyword is :override.

If nested dynamically only the outer call to with-compilation-unit has any effect unless the value associated with :override is true, in which case warnings are deferred only to the end of the innermost call for which override is true.

The function compile-file provides the effect of

(with-compilation-unit (:override nil) ...)

around its code.

Any implementation-dependent extensions can only be provided as the result of an explicit programmer request by use of an implementation-dependent keyword. Implementations are forbidden from attaching additional meaning to a use of this macro which involves either no keywords or just the keyword :override.

Examples:

If an *implementation* would normally defer certain kinds of warnings, such as warnings about undefined functions, to the end of a compilation unit (such as a *file*), the following example shows how to cause those warnings to be deferred to the end of the compilation of several files. 
(defun compile-files (&rest files) 
  (with-compilation-unit () 
    (mapcar #’(lambda (file) (compile-file file)) files))) 
(compile-files "A" "B" "C") 
Note however that if the implementation does not normally defer any warnings, use of *with-compilation-unit* might not have any effect.

See Also:

compile, compile-file

System

∗features∗

Expanded Reference: with-compilation-unit​

Deferring warnings across multiple compilations​

with-compilation-unit groups multiple compilations together so that deferred warnings (such as "undefined function") are not issued until the entire unit is complete.

(defun compile-my-system ()
  (with-compilation-unit ()
    (compile-file "/tmp/cl-wcu-a.lisp")
    (compile-file "/tmp/cl-wcu-b.lisp")
    (compile-file "/tmp/cl-wcu-c.lisp")))

Using with mapcar​

A common pattern is to compile a list of files within a single compilation unit.

(defun compile-files (&rest files)
  (with-compilation-unit ()
    (mapcar #'compile-file files)))

The :override option​

Normally, only the outermost with-compilation-unit controls when deferred warnings are emitted. The :override t option forces an inner form to act as its own compilation unit.

(with-compilation-unit ()
  ;; Warnings deferred to end of outer unit
  (compile-file "/tmp/cl-wcu-a.lisp")
  (with-compilation-unit (:override t)
    ;; Warnings deferred only to end of this inner unit
    (compile-file "/tmp/cl-wcu-b.lisp")))

Returns the values of the body​

The macro returns the values of the last form in its body.

(with-compilation-unit ()
  (values 1 2 3))
=> 1
=> 2
=> 3