Compiler Definitions
********************

 -- Function: EMIT-FN (turn-on)
     Package:COMPILER

     If TURN-ON is t, the subsequent calls to  COMPILE-FILE will cause compilation of foo.lisp to emit a foo.fn as well as foo.o. The .fn file contains cross referencing information as well as information useful to the collection utilities in cmpnew/collectfn This latter file must be manually loaded to call emit-fn.

 -- Variable: *CMPINCLUDE-STRING*
     Package:COMPILER If it is a string it holds the text of the cmpinclude.h file appropriate for this version.  Otherwise the usual #include of *cmpinclude* will be used.  To disable this feature set *cmpinclude-string* to NIL in the init-form.

 -- Function: EMIT-FN (turn-on)
     Package:COMPILER

     If TURN-ON is t, then subsequent calls to compile-file on a file foo.lisp cause output of a file foo.fn.  This .fn file contains lisp structures describing the functions in foo.lisp.  Some tools for analyzing this data base are WHO-CALLS, LIST-UNDEFINED-FUNCTIONS, LIST-UNCALLED-FUNCTIONS, and MAKE-PROCLAIMS.

     Usage: (compiler::emit-fn t) (compile-file "foo1.lisp") (compile-file "foo2.lisp")

     This would create foo1.fn and foo2.fn.  These may be loaded using LOAD.  Each time compile-file is called the data base is cleared.  Immediately after the compilation, the data base consists of data from the compilation.  Thus if you wished to find functions called but not defined in the current file, you could do (list-undefined-functions), immediately following the compilation.  If you have a large system, you would load all the .fn files before using the above tools.

 -- Function: MAKE-ALL-PROCLAIMS (&rest directories)
     Package:COMPILER

     For each D in DIRECTORIES all files in (directory D) are loaded.

     For example (make-all-proclaims "lsp/*.fn" "cmpnew/*.fn") would load any files in lsp/*.fn and cmpnew/*.fn.

     [See EMIT-FN for details on creation of .fn files]

     Then calculations on the newly loaded .fn files are made, to determine function proclamations.  If number of values of a function cannot be determined [for example because of a final funcall, or call of a function totally unknown at this time] then return type * is assigned.

     Finally a file sys-proclaim.lisp is written out.  This file contains function proclamations.

     (load "sys-proclaim.lisp") (compile-file "foo1.lisp") (compile-file "foo2.lisp")

 -- Function: MAKE-PROCLAIMS (&optional (stream *standard-output*))
     Package:COMPILER

     Write to STREAM the function proclaims from the current data base.  Usually a number of .fn files are loaded prior to running this.  See EMIT-FN for details on how to collect this.  Simply use LOAD to load in .fn files.

 -- Function: LIST-UNDEFINED-FUNCTIONS ()
     Package:COMPILER

     Return a list of all functions called but not defined, in the current data base (see EMIT-FN).

          Sample:
          (compiler::emit-fn t)
          (compile-file "foo1.lisp")
          (compiler::list-undefined-functions)
          or
          (mapcar 'load (directory "*.fn")) (compiler::list-undefined-functions)

 -- Function: WHO-CALLS (function-name)
     Package:COMPILER

     List all functions in the data base [see emit-fn] which call FUNCTION-NAME.

 -- Function: LIST-UNCALLED-FUNCTIONS ()
     Package:COMPILER

     Examine the current data base [see emit-fn] for any functions or macros which are called but are not: fboundp, OR defined in the data base, OR having special compiler optimizer properties which would eliminate an actual call.

 -- Variable: *CC*
     Package:COMPILER Has value a string which controls which C compiler is used by GCL. Usually this string is obtained from the machine.defs file, but may be reset by the user, to change compilers or add an include path.

 -- Variable: *SPLIT-FILES*
     Package:COMPILER This affects the behaviour of compile-file, and is useful for cases where the C compiler cannot handle large C files resulting from lisp compilation. This scheme should allow arbitrarily long lisp files to be compiled.

     If the  value [default NIL] is a positive integer, then the source file will be compiled into several object files whose names have 0,1,2,.. prepended, and which will be loaded by the main object file.     File 0 will contain compilation of top level forms thru position *split-files* in the lisp source file, and file 1 the next forms, etc.   Thus a 180k file would probably result in three object files (plus the master object file of the same name) if *split-files* was set to 60000. The package information will be inserted in each file.

 -- Variable: *COMPILE-ORDINARIES*
     Package:COMPILER If this has a non nil value [default = nil], then all top level forms will be compiled into machine instructions.    Otherwise only defun's, defmacro's, and top level forms beginning with (progn 'compile ...) will do so.