PDP-10.its/doc/kcc/port.doc

		INSTALLING AND PORTING KCC

	This file tries to document various things about porting KCC to other
systems; including how to bring up new versions on systems which already have
KCC.

	A "port" involves two major things: the KCC compiler itself, and
the C library (LIBC).  They are interdependent, and since the compiler is used
to compile itself, things have to be done carefully.

	KCC supports all CPUs: KA, KI, KS, KL, KX.  System is irrelevant.
	LIBC supports only TOPS-20.  There is partial (but not complete)
		support for TOPS-10, WAITS, and ITS.

The usual situations are these:

(1) Installing KCC and the library for the first time.
(2) Installing a new version of the C library or KCC.
(3) Using KCC as a cross-compiler for another CPU or system.
(4) Porting KCC and the library to a different CPU or system.

Other references:
	For (1) see the distribution INSTAL.DOC file.
	The KCC USER.DOC section about cross-compiling.
	The C library file LIBC.DOC.

Building and installing a compatible new version of KCC/LIBC for your current
system:

	If the new version has exactly the same site-dependent parameters
(C-ENV.H and CCSITE.H) then you can simply install the new binary, without
bothering to recompile from the sources.

	If your site-dependent parameters are different from that of the
distributed KCC then you will need to recompile from the sources.  To do
this,
	1. Make sure that the C-ENV.H in the KCC source directory is correct
	(or, if it doesn't exist, that the version in the include directory
	is correct).  Ditto your CCSITE.H or whatever is different.
	2. On TOPS-20, simply invoke CC.MIC, as in "DO CC".  Or do it by hand.
	Then install the resulting NCC.EXE on your system as "CC".

	NOTE: if the new version of KCC makes some changes in its runtime
assumptions, you may need to change some other things.  The most that may be
required is to follow the cross-compilation procedure as if porting to a new
system.  If you know what is going on, you may be able to get by with less
than a full new installation.

Using KCC as a cross-compiler:

	This assumes you want to set things up on your source system so
that you can compile programs into binaries which can then be moved to
a target system and executed there.  This can sometimes be useful if the
target system is not really able to run KCC itself for whatever reason.
Also, we assume that the source system is a TOPS-20, since KCC is fully
supported for that system and the existence of logical names makes things
easier.

[1] Set up a new directory to serve as the standard include (and library)
directory for the target system's files.  For the sake of the following
discussion, call this directory NC:.

[2] Install in NC: an appropriately editted copy of C-ENV.H.
	In particular, CPU_xxx and SYS_xxx must be set properly.

[3] Build a program called, for example, XCC which passes its arguments on
	to an invoked CC with the addition of appropriate switches.
	See the program TCC.C in the KCC source directory for a sample;
	this program runs on TOPS-20 and compiles code for TENEX.
	The following switches should be set:
		-L to specify the library directory path (NC:)
		-H to specify the standard include file directory path (NC:)
		-x to specify the target CPU, system, and assembler
	And others such as -A if necessary.

[4] Use XCC to recompile and rebuild the entire C library.  Install the
	new LIBC.REL in NC:.

[5] That's it.  KCC does not need to be rebuilt, since XCC will simply
	invoke KCC with the appropriate switches set.  Whenever making
	a program to run on the target machine, just use XCC.

KCC/LIBC Cross-compilation (using logical names):

	These are the complete steps to follow when building a new KCC and
LIBC for another CPU or system.  You may be able to get by with doing less,
if you know what is going on and what the changes are.  You may have to
do more, if the new CPU or system is not fully supported.

	This procedure for cross-compiling KCC/LIBC for a different CPU/system
relies on TOPS-20 logical names, and assumes that the logical name C: is used
by the source machine's KCC to refer to both the standard include directory
and the library directory.  If some other logical name is used, substitute
that for C: in the following discussion.

[0] Redefine C: to be a search path pointing FIRST to a "new" standard
	directory, and SECOND to KCC's standard directory (normally
	this is the system-wide logical name C:).
	This requires the user to:
		@define C: <new-dir>, C:

[1] Edit C:C-ENV.H for new configuration; write out to C: (new dir).
	In particular make sure that the SYS_xxx and CPU_xxx defaults are set.
	Make sure that any local copies of C-ENV.H (in the KCC or LIBC
	source directories) are identical.
	The same applies to any other .H files that need to be changed; new
	versions should be put in C: (new dir) and local copies made identical
	or flushed.

[2] Connect to the LIBC source directory.
	Delete all .REL files (@DEL *.REL,<.*>*.REL)

[3] Rebuild entire library with the LIBC.MIC file (@DO LIBC).
	Edit LIBC.MIC beforehand to add any -x= switches that are necessary,
	for example -x=ki, -x=klx.  These switches should match with
	the definitions in C-ENV.H!!!

[4] Install new LIBC.REL into C: (@COPY LIBC.REL.0 C:*.*.*)

[5] Also install the new LIBCKX.REL file into C:.  This is necessary in
	order to allow loading of extended-addressing programs.  If your
	machine does not support extended addressing, of course, you can
	ignore this file.

	--- At this point the new library is ready! ---

[6] Build a new KCC:
	Connect to the KCC source directory.
	Make sure that the site-dependent defaults in CCSITE.H are okay.
	Other parameters can be changed in CCPARM.H if necessary.
	Make sure that the local copy of C-ENV.H is either flushed or
	is the same as the version in the new C:.

[7] Delete all the old .REL files (@DEL *.REL).
[8] Compile and load all the C modules with the CC.MIC file (@DO CC).
	Edit CC.MIC beforehand to add any -x= switches that are necessary,
	for example -x=ki, -x=klx.
	This will automatically load up some library routines from the new
	LIBC.  You now have a binary KCC for the target system.

[9] To install on your own system:
	you can replace the old C: by new C: in either of two ways:
	A. (quick) Copy all new C: files over to old C:
		Then undefine your job-wide C:.
	B. (cautious) Copy all remaining files from old C: to new C:.
		Test it out.  If no problems, then revise the system-wide
		logical name.  If problems, swap the names back.

[10] To install on another system:
	On target system, set up the include directory.
	Copy all files from new C: to target (.H files plus LIBC.REL),
		then all remaining files from old C: to target.
	Copy the new CC binary to whereever the target's system progs live.
	If desired, copy the LIBC and KCC sources too.

Cross-compilation without logical names:

	This is a little harder because the source and target directories have
to be more explicitly specified.  In the following discussion, the strings OLD
and NEW are assumed to represent the paths for the old (existing) standard
directory, and the new directory where the new .H files and library will be
written and stored.
		
[1] Edit C-ENV.H for new configuration; write out to NEW.
	In particular make sure that the SYS_xxx and CPU_xxx defaults are set.
	Make sure that any local copies of C-ENV.H (in the KCC or LIBC
	source directories) are identical.
	The same applies to any other .H files that need to be changed; new
	versions should be put in NEW (new dir) and local copies made identical
	or flushed.

[2] Connect to the LIBC source directory.
	Delete all .REL files.

[3] Rebuild entire library.  The LIBC.MIC file shows which files need
	to be compiled and loaded into a library.
	All compilations should be of this form:	
		CC -c -LNEWLIB -INEW -IOLD -x=ki module.C
	Where:
	  "-x=ki" illustrates how a specific CPU must be selected.
	  "module" is the library module being compiled.
	  "NEWLIB" is the path for library modules in NEW, e.g. -LC:LIB=.REL
		The need to specify this is an unfortunate artifact of
		the way library load requests are inserted into the code.

[4] Build all the .REL files together into a library; the first two
	files must be CPU.REL and CRT.REL.  Move this file into the NEW
	directory.

	--- Now start building the new KCC ---

[5] Build a new KCC:
	Connect to the KCC source directory.
	Make sure that the site-dependent defaults in CCSITE.H are okay.
	In particular make sure that LIBPREFIX and LIBPOSTFIX match
	what was given in the -LNEWLIB switch while compiling LIBC.
	Other parameters can be changed in CCPARM.H if necessary.
	Make sure that the local copy of C-ENV.H is either flushed or
	is the same as the version in NEW.

[6] Delete all the old .REL files.
[7] Compile and load all the C modules specified by the CC.MIC file.
	Use the same form as for compiling the LIBC modules, including
	the -L, -I, -x, and -A switches.
	You will then have a binary KCC suitable for the target system.

[8] To install on your own system:
	you can replace OLD by NEW in either of two ways:
	A. (quick) Copy all NEW files over to OLD.  Install the KCC binary.
	B. (cautious) Copy all remaining files from OLD to NEW.
		Test it out.  If OK, install the KCC binary.

[9] To install on another system:
	On target system, set up the include directory.
	Copy all files from NEW to target (.H files plus LIBC.REL),
		then all remaining files from OLD to target.
	Copy the new CC binary to whereever the target's system progs live.
	If desired, copy the LIBC and KCC sources too.

Thoughts on future port to ITS:

Main problem is that the only linking loader available on ITS is
STINK, which only understands STINK format .REL files.  There may be
an old version of the DEC linker available, but this is non-supported
and painful to use.  Finally, MIDAS can produce either STINK or DECREL format;
the ITS version of FAIL can do the same.  This gives us only three
possibilities, in increasing order of generality:
	(1) Use ITS FAIL, producing STINK format.
	(2) Make KCC produce MIDAS output.  Use MIDAS, with STINK format.
	(3) Make STINK understand DECREL format.  Use MIDAS or FAIL.

Note that if KCC is ever improved to bypass the assembler phase by
outputting .REL files directly, it will either have to also know about
STINK format, or STINK will have to know about DECREL format.  The latter
is most general.

Actual porting:

Approach 1: build a KCC elsewhere, dump in old DECSAV format.  FTP over
	and convert to SBLK executable format.
Approach 2: generate complete set of .FAI files and then FTP them.
	Run ITS FAIL to generate STINK format rels,
	then STINK them together to produce KCC and CLIB.
Approach 3: generate complete set of .MID files and FTP them.
	Run MIDAS and then STINK the results together.
Approach 4: generate complete set of .REL files and FTP them.
	Modify STINK to understand DECREL format, load files with STINK.

Fixing KCC to produce valid MIDAS output will require:
	(1) Modifying KCC to produce common assembler subset.  Can do.
	(2) Modifying the syntax of all assembler runtimes.  This is
		the real problem.  Only hope for dealing with this reasonably
		is to change everything to use new #ASM feature; then KCC
		can conditionalize the syntax depending on system.

Library routines required by KCC:

(this list can be generated by loading all .REL modules and then
giving the /UNDEF switch to LINK)

        $$$CPU  0	
        $$$CRT  0		; * C Runtime stuff, in CRT.C
	        $BPCNT  413166
	        $BYTE   517604
	        $DFIX   437543
	        $NSPOP   472623
	        $NSPUS  472615
	        $START  403165
	        $SUBBP  413303
	        $ZERO   463273

	Sys-dependent routines
	        .CPUTM  403072		; * All systems supported
	        EXIT    441516		; *
	        GETPID  517376		; *	CCASMB for temp files
	        JSYS    517315		; T20 - CCASMB for PRARG%
	        PFORK   517675		; T20,10X - CCASMB for asm/link invoke
****>	        UNLINK  517225		; T20,10X,ITS - CC to flush asm files
					; Needs LOOKUP+RENAME for T10/WAITS
	STDIO			; * STDIO stuff.  Should not be sys-dep
	        .SIOS   0
	        FCLOSE  517443
	        FFLUSH  517666
	        FGETC   517212
	        FOPEN   517417
	        FPRINT  516663
	        FPUTC   515464
	        FPUTS   517440
	        FWRITE  516627
	        SPRINT  517407
	        UNGETC  412045
	Stg alloc		; * Depends on S/BRK, all sys supported.
		FREE    442156
	        MALLOC  517154
	        REALLO  517235
	STRING			; * (no sys-dep stuff)
	        STRCAT  414767
	        STRCMP  417712
	        STRCPY  517371
	        STRLEN  517335
	Misc library
	        QSORT   457226	; * (no sys-dep stuff)