Function compile-file

Syntax:

Arguments and Values:

input-file—a pathname designator. (Default fillers for unspecified components are taken from *default-pathname-defaults*.)

output-file—a pathname designator. The default is implementation-defined.

verbose—a generalized boolean. The default is the value of *compile-verbose*.

print—a generalized boolean. The default is the value of *compile-print*.

external-format—an external file format designator. The default is :default.

output-truename—a pathname (the truename of the output file), or nil.

warnings-p—a generalized boolean.

failure-p—a generalized boolean.

Description:

25.1.0 7compile-file transforms the contents of the file specified by input-file into implementation-dependent binary data which are placed in the file specified by output-file.

The file to which input-file refers should be a source file. 25.1.0 8output-file can be used to specify an output pathname; the actual pathname of the compiled file to which compiled code will be output is computed as if by calling compile-file-pathname.

If input-file or output-file is a logical pathname, it is translated into a physical pathname as if by calling translate-logical-pathname.

!!! This leading semicolon stuff is stupid. -kmp 25-Jan-92 If verbose is true, \funref{compile-file} prints a message with a leading \term{semicolon} (a comment) to \term{standard output} indicating what file is being compiledcompile-file prints a message in the form of a comment (i.e., with a leading semicolon) to standard output indicating what file is being compiled and other useful information. If verbose is false, compile-file does not print the informational message.this information.

If print is true, information about top level forms in the file being compiled is printed to standard output. Exactly what is printed is implementation-dependent, but nevertheless some information is printed. If print is nil, no information is printed.

The external-format specifies the external file format to be used when opening the file; see the function open. compile-file and load must cooperate in such a way that the resulting compiled file can be loaded without specifying an external file format anew; see the function load.

\funref{compile-file} uses \funref{read} to read \term{forms} from the input file. compile-file binds *readtable* and *package* to the values they held before processing the file.

!!! Can this be said more compactly or not at all? *compile-file-truename* is bound by compile-file to hold the truename of the pathname of the file being compiled.

*compile-file-pathname* is bound by compile-file to hold a pathname denoted by the first argument to compile-file, merged against the defaults; that is, (pathname (merge-pathnames input-file)).

The compiled functions contained in the compiled file become available for use when the compiled file is loaded into Lisp. Any function definition that is processed by the compiler, including #'(lambda ...) forms and local function definitions made by flet, labels and defun forms, result in an object of type compiled-function.

The primary value returned by compile-file, output-truename, is the truename of the output file, or nil if the file could not be created.

I replaced the language that was here with a copy of what is already said for COMPILE. --sjl 7 Mar 92The secondary value, warnings-p, is false clarify ``compiler diagnostics'' --sjl 7 Mar 92 if no compiler diagnostics were issued, and \term{true} otherwise.if no conditions of type error or warning were detected by the compiler, and true otherwise.

The tertiary value, failure-p, is false clarify ``compiler diagnostics'' --sjl 7 Mar 92 if no compiler diagnostics other than \term{style warnings} were issued. A value of \term{true} indicates that there were serious compiler diagnostics issued, or that other \term{conditions} \oftype{error} or \typeref{warning} (but not \oftype{style-warning}) were signaled during compilation.if no conditions of type error or warning (other than style-warning) were detected by the compiler, and true otherwise.

For general information about how files are processed by the file compiler, see Section 3.2.3 (File Compilation).

This is said below now. --sjl 7 Mar 92 For a description of signaling and handling of errors by the \term{file compiler}, \seesection\FileCompilerExceptions.

Programs to be compiled by the file compiler must only contain externalizable objects; for details on such objects, see Section 3.2.4 (Literal Objects in Compiled Files). For information on how to extend the set of externalizable objects, see the function make-load-form and Section 3.2.4.4 (Additional Constraints on Externalizable Objects).

Examples:

None.

Affected By:

The computer's file system.

Exceptional Situations:

The following information is mostly redundant with info in the chapter 3 concept section, and contains some inconsistencies. Better to just put in a cross-reference. --sjl 4 mar 92 \issue{COMPILER-DIAGNOSTICS:USE-HANDLER} The following list considers only those conditions signaled by, not within, the compiler. An error \oftype{error} might be signaled by the compiler in situations where the compilation cannot proceed without intervention. Examples include file open errors and syntax errors. A condition \oftype{warning} \editornote{KMP: I guess we should add ``correctable by muffle-warning''.} might be signaled by the compiler in situations where this standard explicitly states that a warning must, should, or might be signaled. Also, an error \oftype{warning} might be signaled by the compiler in 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. Examples include violation of type declarations, \term{assigning} or \term{binding} a \term{constant variable}, calling a built-in Lisp function with the wrong number of arguments or malformed keyword argument lists, referencing a variable declared \declref{ignore}, and the usage of unrecognized declaration specifiers. The compiler is permitted to signal errors \oftype{style-warning} about matters of programming style. Although \term{style warnings} might be signaled in these situations, no implementation is required to signal them. However, if an implementation does choose to signal an condition about matters of programming style, that condition is \oftype{style-warning} and is signaled by a call to \funref{warn}. Examples include redefinition of a \term{function} with a different argument list, calling a \term{function} with the wrong number of arguments, \term{accessing} unreferenced local variables not declared \declref{ignore}, and usage of declaration specifiers described in this standard but ignored by the compiler. \endissue{COMPILER-DIAGNOSTICS:USE-HANDLER}

For information about errors detected during the compilation process, see Section 3.2.5 (Exceptional Situations in the Compiler).

An error of type file-error might be signaled if (wild-pathname-p input-file) returns true.

If either the attempt to open the source file for input or the attempt to open the compiled file for output fails, an error of type file-error is signaled.

See Also:

compile, declare, eval-when, pathname, logical-pathname, Section 20.1 (File System Concepts), Section 19.1.2 (Pathnames as Filenames)

Notes:

None.