Small-C Version 2.1

               Documentation File of 15 March 1985

                          W. E. Boebert

Disclaimer:  This compiler has been verified to the extent that
it correctly compiles itself and the subset of the library that
it uses.  Based on the dismaying number of typos I found in
getting it to that state, I am not willing to guarantee that
there may not be more in there somewhere.  Such are the vagaries
of the ten-digit interface, and I apologize in advance for any
difficulties anybody may encounter in using this thing.

Overview:  These files contain the Small-C compiler first written
by Ron Cain and upgraded by James E. Hendrix, and the library of
functions written by James E. Hendrix and Ernest Payne.  I have
entered them, debugged them to the degree described above, and
made some trivial changes to correct typos, get them to work
together, and to fix problems in two of the library functions.
The compiler is documented in The Small-C Handbook by James E.
Hendrix (Reston, 1984, ISBN 0-8539-7012-4) and the library
appeared in Dr. Dobbs for May and June 1984.

Required Support:  The compiler translates a useful subset of the
C language into assembly code for a linking CP/M assembler (not
included).  The assembler must follow the naming of conventions
of MAC-80 or M80. External names are denoted by means of an
external declaration (e.g., EXT FOO) or by having "##" as the
last two characters (e.g., CALL FOO##).  Public names are denoted
by "::" (e.g., FOO:: CALL FEE).  The assembler must be able to
handle names that start with an underscore (e.g., "_read").

Use of the Compiler: Full details on I/O redirection and command
line entries appear in the Handbook, and will not be repeated
here.  Once you have compiled PROG.C into PROG.MAC and then
assembled it into PROG.REL, link it into the library using the
command

L80 PROG, CLIB/S, PROG/N/E

to get PROG.COM.

Mods and Fixes: Certain mods were made to make the linkage
process work properly.  The code for program initiation and
termination, described in Dr. Dobbs,  was added to CALL.MAC; this
code does not appear in the Handbook.  The function "trailer()"
in file cc41.c was changed to search the symbol table for a
function named "main;" if it finds one, it knows it has compiled
a main program and it appends the external reference (described
in Dr. Dobbs) which forces the loading of the CSYSLIB module.

The order of the functions in CLIB.REL was changed from Dr. Dobbs
to accomodate the L80 "feature" that names are searched for only
in a forward direction; this means that any name defined as
external in one module must be defined as public in a later
module in the file.  You should use the /L option of LIB80 to
list the library and make sure you relink it in this order if you
make any changes.

The .DEF files in Dr. Dobbs and the Handbook differed in the
definition of NEWLINE; the library and the compiler now both use
CR (13) instead of LF (10).

The library function fclose() was modified to insure that an EOF
character is always appended to the end of the data.  This was
not a problem within library functions, which recognize either an
EOF or physical end of file as logical EOF; however, certain
non-Small-C applications expect the EOF character and are now
sure to get it.

The function auxbuf() and associated references to it have been
deleted from the library.  The listing in Dr. Dobbs indicates
that early versions of the compiler have bugs which would cause
bad code to be generated for this function, but that the
situation was fixed in Version 2.1.  Well, either I mistyped the
fix or they are mistaken, because references to auxbuf() would
intermittently crash.  I view the function as being of marginal
utility, so rather than chase the problem down I just deleted it.

A couple of pasteup errors and one declaration error were
discovered and the fixes noted in comments.

Modifying the Compiler: The most likely mod you will want to make
is to automatically output some assembly header or trailer
information.  To do this you change the functions "header()" or
"trailer()" in cc41.c.  The function "ol(string)" is used to
output a line.  

For example, my version of M80 is the one in Microsoft's Assembly
Language Development System for the Apple; it defaults to the Z80
opcodes and requires a ".8080" pseudo-op to assemble in that
mode.  To avoid cluttering up my C programs with spurious "#asm"
clauses, I modified "header()" to read:

header() {
  beglab=getlabel();
  ol(".8080");
  }

and get it automatically.  The compiler is currently #define'd
for separate compilation; you will have to recompile cc1.c,
cc2.c, cc3.c, and cc4.c, and relink the corresponding .REL files
with the command

L80 CC1, CC2, CC3, CC4, CLIB/S, CC/N/E

as the compiler uses the I/O library.  Enjoy.

-- Earl Boebert