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

		KCC Runtime Library Coding

	This file is oriented towards KCC implementors and describes
some general rules for writing C library functions, along with a more
detailed explanation of certain crucial files in the library.

	The source for all library routines is kept in <xx.LIB> where
"xx" depends on your system; on the distribution it is usually something
like "KCC-4".  Since that doesn't matter here, it will be left out of
any filenames mentioned.

    <.LIB*>	Runtime library sources:			Documented in:
	<.LIB>		General-purpose library routines.	(LIBC.DOC)
	<.LIB.STDIO>	Standard I/O package routines.		(LIBC.DOC)
	<.LIB.MATH>	Math library routines.			(LIBC.DOC)
	<.LIB.USYS>	Unix simulation routines.		(USYS.DOC)
	<.LIB.NETWORK>	A stab at a couple BSD net routines.	(LIBC.DOC)
	<.LIB.PML>	Unused "portable math library" routines.
	<.LIB.TEST>	Unused testing routines.

Guidelines for writing C library modules:

	ALWAYS #include "c-env.h" before anything else, unless the
code is truly portable and completely in C.  Note this is "c-env.h",
not <c-env.h>, so that it is easy to test variations.

	All source files for KCC and the LIBC routines should refer to
their header files with "" instead of <>, so that different versions
of the .H files can be tested easily in the source directory before
installation in the system-wide standard location.  Normal compilation
can simply point to the standard include-file location with the -I
switch.  However, note that user programs, unlike the library sources,
should always use <>.

	Keep all versions of a function together in the same file,
rather than having a different file for each version depending on the
system.  Just conditionalize any system-dependent code appropriately.

	If trying to assemble for an unsupported system or CPU, invoke
the #error preprocessor command to cause a compilation error with an
appropriate message.  Alternatively, if it is important that a
function symbol exist even though it is unsupported, you can code for
a function that always fails with an error printout to stderr.

	In general each specific library function should have its own
individual file, although several functions can be collected in the
same file if they are really tightly bound together.  Any routine that
needs to use a system call should consider using #asm for efficiency,
instead of the jsys() or syscal() functions. (This is not normally
recommended, but since library routines are heavily used and rarely
modified, it's somewhat more acceptable.)


ASSEMBLER HACKERS:
	.FAI or .MAC source modules should never exist.  Functions which
require assembly code should use the #asm or asm() feature of KCC.
See the KCC user documentation for details on this.
	Use $ or % for runtime-only externals, switches, and macros,
to avoid possible conflict with C symbols.  Remember "_" in a C symbol is
equivalent to "." in an assembler symbol.
	The C runtime support has the following symbol conventions:
		$$$xxx		Major module entry name.
		$$xxxx		Global symbol value, internal to runtimes.
		$xxxxx		Global label, internal to runtimes.
		%xxxxx		Macro-type instruction.
		%%xxxx		Miscellaneous macro function.

USYS routines:
	If writing a UNIX system-call simulation routine (which should
go into <.USYS>), there are additional things to be careful of, and the
file USYS.DOC should be consulted.

IMPORTANT FILES:

C-ENV.H	- C Environment defs.  Contains all system/CPU configuration defs.
	Copy kept in standard include dir.

	Should be included by every LIBC routine which has any system
or environment dependencies.  Different versions of this file exist
for different systems/machines/configurations.  Can also be included
by user programs.  IFNDEFs allow testing temporary changes by using
the -D switch, although this should be done in conjunction with the
appropriate -x= switches.


CPU.C	- Load-time CPU definitions for target machine, determined by C-ENV.H.
	Entry point: $$$CPU (a dummy)

	This module is part of the C library and defines the values for
several symbols which depend on the specific processor that the program
is being loaded for.  The primary usefulness of this module is that it
allows the user to defer until load time the decision of whether to build
a program for extended or non-extended operation.  It also sets the right
symbols to ensure that all loaded modules are compatible with the CPU type
being loaded for.

CRT.C	- Standard C Run Time support for KCC.
	Entry point: $$$CRT (a dummy)
	Globals: $START			Startup
		__EXIT			Exit
		_END,_ETEXT,_EDATA,_EALLOC	Hack: Unix simul (shd move)
		$RET,$RETF,$RETZ,$RETT,$RETP,$RETN	Return points
		$ZERO			Handy zero constant
		$ADJBP			ADJBP simulation
		$Bxxxx			Various byte-pointer tables
	All C programs start here.  CRT is responsible for setting up
the C environment so that C code can execute properly.  It specifically
does not do anything about setting up a UNIX environment; that is up to
whatever it is loaded with.  When the C environment is ready, it calls
the routine _runtm() which should perform any remaining setup and then
call main().  Normally this routine is found in URT.C, the Unix-simulation
Run Time module.


URT.C	- UNIX-simulation Run Time support (in <.LIB.USYS>)
	Entry points: _RUNTM EXIT .EXIT ERRNO

	This module is written in C, and is called by CRT once the C
environment is set up.  URT then sets up the UNIX simulation
environment, parsing the command line and setting up stdin, stdout,
and stderr.  When ready, it calls the user's main() function with the
parsed command line as a normal "argc,argv" array of char pointers.