Distribution Disk - Shareware Atari ST C compiler - version 2.0
         copyright 1988 - Mark A. Johnson
                          5315 Holmes Place
                          Boulder, CO 80303
                          GEnie login: MAJOHNSON

This disk contains a shareware C compiler for your use and enjoyment,
pass it on to anyone freely as long as it includes this note.

I bought my 520ST in April 1986.  Almost all the software I have is either 
public domain or shareware.  I have supported the shareware idea in the past,
but I'd like to see it happen for myself.  If you like what you find here,
please send a donation along with your name and address.  I send out a
newsletter to discuss bugs, enhancements, and hints now and then.  I hope 
you enjoy this software.  It is not for sale by anyone, and I reserve all 
rights to its  ownership.  Feel free to pass it on to other ST owners, 
but please pass on the whole disk, including this "readme" file.  

This is the distribution disk for version 2.0 of the compiler.
It contains the basic compiler tools, libraries, source for the libraries, 
source for a number of useful tools, and (hardly any) documentation.

The compiler can handle the full language specified in Kernigan & Ritchie's
"The C Programming Language." To save space, the distribution is contained 
in three ARC files:

    mjc.arc	- the compiler development environment
    lib.arc	- source code for the libraries
    srcdoc.arc	- source code for a few useful tools and documentation

I've also included ARC.TTP to allow you to unpack the disk.  
Here's a description of the files contained in the all the archives:

Programs
    cc.ttp	- translates C code to intermediate code
    as.ttp	- translates intermediate code to machine code
    ue.ttp	- public domain microEmacs editor 
    mk.ttp	- simple UN*X style "make" program
    eternal2.prg- a PD ramdisk, survives resets
    ramdisk.dat - data file for ramdisk
    autodisk.prg- Moshe Braner's autoboot floppy copy to ramdisk on boot

Libraries and Header Files
    prg.s	- startup intermediate code for .PRG programs
    ttp.s	- startup intermediate code for .TTP programs
    lib.a	- library used to create .TTP programs
    gem.a	- library used to create .PRG programs
    lib.c	- source for most of lib.a
    math.c	- source for the long and floating point math routines
    str.c	- source for the string routines
    fmtio.c	- source for printf, scanf, and all its friends
    gem.c       - source code for gem.a
    stdio.h	- header for the standard i/o routines
    setjmp.h	- header for setjmp/longjmp routines
    gem.h	- header for GEM AES routines
    osbind.h	- header for "standard" GEMTOS bindings

Source code
    ss.c	- a simple spreadsheet program
    hd.c        - a hex dump program
    mk.c	- the make program used in the development environment
    lorder.c	- a library checker (makes sure the order is ok)
    bug.c       - tells you what happened in a crash
    
Documentation
    as.doc	- documentation on the intermediate code
    readme.doc	- this file
    eternal2.doc- describes ramdisks in general and eternal2 in particular
    autodisk.doc- describes what autodisk.prg does and how to use it

I have a 520ST with one single-sided floppy, so this disk is really a
collection of many disks I use.  Let's get started by making an autobooting
development environment disk.  Copy MJC.ARC and ARC.TTP to a fresh floppy
and extract all the files out of MJC.ARC (see ARC.DOC).  Then do the 
following (in order):

	create an AUTO folder
	copy ETERNAL2.PRG into AUTO
        copy AUTODISK.PRG into AUTO
        copy RAMDISK.DAT into AUTO
        the following files should be in the root directory
		UE.TTP
		CC.TTP
		AS.TTP
		MK.TTP
		TTP.S
		LIB.A
		DESKTOP.INFO

Now, whenever you boot the system with this disk, it will prompt you for the
date (it's important to tell it the truth, MK.TTP uses file timestamps
to tell whether or not to build something), copy all the files to the
ramdisk, and then puts you back on the desktop.

The compiler (CC.TTP) is preprocessor, parser, and code generator all rolled
into a single program.  Please refer to the "C Programming Language" by K&R.
The compiler has the following features beyond K&R:

    - symbol names can be any length
    - built-in 6800 trap generator "trap(NUM, arg1, arg2, ...)"
    - structure assignments
    - register variables
    - "assembler" escapes
    - enum's

The floating point is homebrew and new to version 2.0, I am sure it is slow
and buggy.  Be forewarned.  If anyone can improve the floating point code
(see MATH.C in the library source), please let me know so I can 
incorporate it into future releases.

The output of the compiler is ascii text and each line maps into a 
single instruction.  This intermediate code is as terse as I can make it (to
save disk space) but is still readable (by me at least).  (I have plans to 
improve this to make things easier for an optimizer).  The output of the 
compiler is always placed in a file called "yc.out" in the current directory.
Any error messages are displayed on the screen.  If "-o filename" is present
on the command line, output will be placed in the specified file instead of
YC.OUT.  The other options to CC.TTP include "-I directory" which gives the
compiler optional directories to search for include files, and "-D name" or
"-D name=value" which lets you #define things on the command line.

The assembler (AS.TTP) reads the intermediate code in a single pass and 
keeps everything in memory before generating the file "ya.out" in the 
current directory.  The size limit of the program to be compiled is basically
the size of the available memory.  The "ya.out" file should be renamed to 
one of the standard extensions (.TTP, .PRG, .TOS) before executing it.  
The command line of the assembler should always list a startup file 
first (see ttp.s or prg.s) then the intermediate files of the program, 
then "-L" followed by any libraries.  Any errors encountered by the 
assembler terminates assembly.  A "-m" argument to the assembler will 
include the symbol table (standard Atari format) in the output file.  
A "-o filename" argument will place the output in the specified file instead
of in YA.OUT.  Finally, for those times when the command line is too short
(it's only 128 characters on the ST) a "-f filename" allows AS.TTP to read 
in its list of files to be assembled from a file.

A library is simply intermediate code, but is handled differently by the 
assembler than regular intermediate code.  Intermediate code (the 
files before "-L") are read and processed directly; all symbols and
code are accepted without question.  A library is read without processing 
until a symbol is found that is needed but not defined.  From that point 
on, the library is read and processed until the next symbol is encountered.
At the next symbol, the "needed but not defined" test is applied again 
and processing or scanning continues as necessary.

The libraries include TOS, VDI, and AES routines taken from the Abacus books.
See lib.doc for some info on the library routines.  I have also included basic
<stdio.h> routines.  I have included the source for LIB.A and GEM.A.  A lot 
of library routines you would expect to see are missing, and for that I 
apologize.  My next major project for the compiler is to port Dale 
Schumaker's DLIB package to MJC.

Creating .TTP programs is straightforward and better tested than .PRG (GEM) 
program creation.  In a .TTP process, the main function is called with 
the standard arguments:

	main(argc, argv) int argc; char *argv[];

Redirection of input and output using >outfile, >>appendfile, or <infile 
on the command line is handled by a startup routine linked into the 
compiled program.  Reads and writes to the screen are built to map '\n' 
to/from "\n\r".

Support for GEM programs (.PRG) is not completely debugged.  The GEM.A 
library includes all the VDI and AES functions in the Abacus books,
but has not been extensively tested.  The VDI routines work and 
the window routines, form_alert, and evnt_multi of AES are working.  
My stumbling block right now is adequate documentation 
that would enable me to build a (working) Resource Construction Set.  
I'm (still) working on it...  (Actually, I'm ready to give up on GEM and
roll my own window manager that has forms, menus, and windows, and doesn't
need resource files to work).

Let me give you an example of how I use these tools.  I boot with the
disk we made above that sets up my environment with all the tools in
the ramdisk.

I then insert a working disk (I only have a single floppy!).
I use microEmacs (UE.TTP) to create or edit C programs.  The MK.TTP program
has built-in rules that enable it to build .TTP or .PRG programs out of
.C source files without any makefile needed.  MK.TTP also will search for
a drive that has a makefile on it, which for me is normally A:.  When I
start up MK.TTP out of the ramdisk, it usually goes over to A: and starts
doing it's thing.  For example, I click on MK.TTP and in the form enter

	grep.ttp

This will compile the program grep.c and create an executable called grep.ttp.

If the C program is contained in a number of files, I normally create a
makefile MK.TTP can use.  Intermediate files are created from the C source
(again a built-in rule in MK.TTP) and finally the object is linked together
by an entry in the makefile.  For example, say I have a spreadsheet program
composed of four files: main.c, io.c, calc.c, and display.c.  The following
makefile would do the trick:

# makefile for a (mythical) spreadsheet program

OBJ = main.s io.s calc.s display.s

ss.ttp: $(OBJ)
  d:as.ttp d:ttp.s $(OBJ) -L d:lib.a
	
io.c main.c display.c: stdio.h


With the above, I can build the spreadsheet after editing by simply double 
clicking and letting it go.  When you don't tell MK.TTP what to build, it
will build the first object it finds, which in the above example is SS.TTP.

Only those files that need to be compiled will be compiled.  When everything
is compiled then the objects will be linked together to form the executable.
The source for MK.TTP is included SRC.ARC, so take a look in there for more 
information on how it works.  It has lots of functions built-in which you
may find useful.  

If you insist on doing things by hand, then double click CC.TTP and give it
an argument like "file.c".  This will compile FILE.C into intermediate code, 
which is found in YC.OUT in the current directory.  You can then double
click AS.TTP and give it "d:ttp.s yc.out -L d:lib.a" to assemble and link 
the startup file TTP.S, the compiler output YC.OUT and the library LIB.A.  
For GEM programs, you can replace TTP.S with PRG.S and add GEM.A after the -L.

To build libraries or tools, use the compiler.  There are makefiles included
with the source code for them.  Write me if you have problems with any of this!