-*- Mode:Text -*-  COLDLOAD-LOSSAGE.TEXT - Keith Corbett 11/2/88

This document points out some restrictions that should be observed when
modifying system cold-load source files.  This is not an exhaustive list.

1. MAKING COLD-LOAD BAND:

The process of making the CLD (cold-load) band will be terminated by
things COLD:COLD-FASLOAD won't handle.  For example:
	
 - 8-bit binary format .QFASL files (not a problem yet)
 - QFASL op-codes added to system but not added to SYM:FASL-OPS

*** Changes to FASLOAD must be extended to COLD-FASLOAD and MINI-FASLOAD!

I haven't seen these lose, but according to COLDLD.LISP they would:

 - Initializing a displaced array.
 - Arrays other than 1- or 2-dimensional, art-16b or numeric.
   (But strings are OK.)
 - DEFUN function specs other than symbol or property; things like the
   following won't load: (DEFUN (FOO PROP) ...) {What does that mean???}
 - Pathnames that can't be handled as phony pathname strings.  (???)

2.  BUILDING THE NEW SYSTEM BAND:

Both booting the CLD band and running QLD to load the inner system will
terminate on anything that generates an error.

The most common problems are caused by initializations that refer to things
that aren't defined yet, such as DEFVARs that EVAL can't handle. Top-level
initializations are EVAL'd in cold-load during LISP-REINITIALIZE, but (I think)
before ADD-INITIALIZATIONS are done.  These are easy to mess up.

Forward references in general are the most common problem.  For example,
references to COMPILER functions at top level in QFASL.LISP caused problems
when I built system 127.  (QFASL is a cold-loaded file, but the compiler gets
loaded much later, in the third stage, during (MAKE-SYSTEM 'SYSTEM).)

For example:

 - Macros that create forward references (e.g., COMPILER:MAKE-OBSOLETE, when I
   modified it to use FORMAT).

 - Using FORMAT generally won't work.

 - (DEFCONST X (BYTE 3 0)) blows up during load of an INNER-SYSTEM-FILE-ALIST
   file - BYTE just isn't there yet.

 - Anything that uses SIGNAL or error-handling other than FERROR.  For example:

	(ferror "Error in cold load!") - works
	(signal (make-condition ...))  - fails
  
  Note that FERROR may be used, carefully, as a WARN function. Calls to FERROR
  are automatically replaced.  REP-COLD-LOAD prints its args as strings.
  
  - Subtle uses of EVAL. For example, defining a make-system variable that uses
    CASE: when MAKE-SYSTEM gets evaluated in the cold load, it chokes because
    CASE isn't present; this use of CASE is not macro-expanded, it's just data.

Other kinds of problems:

  - The package structure in the cold-load band must reflect that of the world
that builds it.  Problems can occur, for example, if a patch in the "old
world" causes a GLOBAL symbol X to be imported into package FOO.  Then,
references to GLOBAL:X within FOO get compiled as symbols within package FOO
(they are EQ).  But if

  1) The cold load software does not explicitly do the IMPORT as well, or
  2) FOO does not use the GLOBAL package, 

then FOO:X and GLOBAL:X will <not> be EQ in the cold world.  This happened to
the system 129 cold load, with spectacular results.  In system 125,
GLOBAL:ZUNDERFLOW was imported into NETWORK; the system 129 cold world crashed
in the scheduler because binding NET:ZUNDERFLOW did not affect the A-MEM
(Lambda processor-internal) variable ZL:ZUNDERFLOW.