Message-ID: <429@oddjob.UChicago.UUCP>
Date: Sun, 2-Sep-84 03:48:08 EDT
Article-I.D.: oddjob.429
Posted: Sun Sep  2 03:48:08 1984
Date-Received: Mon, 3-Sep-84 10:47:09 EDT
Organization: U. Chicago: Astronomy & Astrophysics
Lines: 518

Here is the sumacc documentation. I hope this does not turn my
mail into net.flame

Sean Casey		...ihnp4!oddjob!sean

----------------------(cut here)-------------------------------
.na
.TL
SUMEX MacC UNIX Development Kit
.AU
Bill Croft
.AI
Stanford University
Medical Center
SUMEX Project, rm TB105
Stanford, CA  94305
.NH
Introduction
.PP
This 'short' note describes the current state of our UNIX/C development
environment for the Macintosh, 
.I SUMacC 
("some-max").  At present the
release must still be considered in a beta test stage.  Although
all the test programs we have tried so far operate correctly,
there are no doubt some minor bugs still lurking in there somewhere.
.PP
We are distributing this package under the condition that it may
be "used" but not "sold" without our permission.
Any fixes or enhancements made to the package should be reported
back to us, for incorporation into future releases.
While we will attempt to fix bugs and provide new features, no
warrantee is expressed or implied.  You are basically on your own.
.PP
Since this is a beta release, and since we are not equipped to
duplicate massive amounts of tapes and disks, we are limiting
distribution to those who can use the Arpanet to FTP a copy from our 
SUMEX-AIM host, or from another nearby host on the Arpanet.
To facilitate this, we ask that anyone picking up a copy be willing
to act as a redistribution point.  Send a note to 
.I croft@sumex
giving the pathname and anonymous FTP login to retrieve a copy from
your host.  I will post a note to 
.I info-mac 
a few days after
release summarizing where folks can pickup a copy.
.NH
Prerequisites
.PP
The package is currently only setup for a VAX running 4.1 or 4.2 BSD
UNIX.  It should be convertable to any other UNIX box having
a 68000 C compiler.  
.PP
We assume you have some release of the Apple 
.I MacTerminal
program.
This is used to download a printable hex file from the VAX
to your Mac disk.
.PP
Since we don't have the resources to duplicate Sony disks for
everyone outside the Stanford community,
we also assume you have access to a Lisa (Mac Workshop) development
system.  This is used, one time only, to put a program on your
Mac disk (called 
.I fromhex
) that takes the printable hex output
from MacTerminal, and turns it into binary resource file (fork).
Below in the 
.B Downloading
section, we discuss possible 
alternatives.
In any case, it's simply handy to have at least one Lisa system
available occasionally, since this is how new software is
released from Apple.
.NH
Contents of the Kit
.PP
The following directories/files are in the distribution:
.IP sumacc.ms 12
This file, in \-ms macro format.
.IP Makefile
Master makefile that calls Makefile's in subdirectories.
.IP cc42
C compiler binaries for 4.2 BSD.
.IP cc41
C compiler binaries for 4.1 BSD.
.IP ccsrc
C compiler source (if provided).
.IP h
Macintosh header files, copied to /usr/include/mac.
.IP lib
Macintosh library files.
.IP cmd
Resource maker and other Macintosh related commands.
.IP test
Some Macintosh C test programs.
.IP man
Manual pages.
.IP ws
Reference copy of most of the sources distributed with the Lisa Workshop.
.NH
Installation
.PP
The makefiles included have been conditionalized so that you can
change where the files reside after installation.  
At Stanford for historical/political reasons
the binaries are in
.I /usr/stanford/bin,
the library stuff goes in
.I /usr/sun/lib,
and the include files are kept in
.I /usr/include/mac,
or
.I /usr/stanford/include/mac.
If you change where things are located, you will have to: (1) edit
the master Makefile and/or the sub-Makefiles to change the installation
directory names.  (2) Edit 
.I cmd/cc68.c, 
the C compiler driver so that
it can find the assembler/loader/etc.  
This is easy to change for
.I /usr/stanford/bin,
but since the 
.I ld68 
and 
.I as68 
binaries provided have
.I /usr/sun/lib
wired in, you may want to leave that one alone.
Use
.I mkdir
to make these directories if they don't already exist.
Another possibility to change the file locations is to use the
symbolic link facility on 4.2 to (e.g.) 
.I
link -s /usr/local /usr/stanford/bin.
.R
.PP
If your VAX doesn't already have
the 68000 compiler installed,
.I cd
to 
.I cc42
or
.I cc41
and type
.I make.
This will install all the compiler binaries (except cc68).
.PP
.I "4.1 BSD:"
If you are running 4.1, edit cmd/cc68.c to remove the '#define BSD42' line.
Also edit lib/Makefile so that the lint library is constructed with 'mk41lint';
(4.1 lint doesnt understand the '\-C' switch.)
.PP
Now from the main directory, do a
.I make.
This will compile and install the commands, Mac library, 
Mac lint library,
include files, manual pages, and test programs.
.PP
If you don't already have a 
.I SUMACC
Sony disk with 
.I MacTerminal
and 
.I fromhex,
then you need to make one.
On a Lisa Mac Workshop system, use the
.I terminal
program to download the file
.I cmd/fromhex.p
from the VAX to the Lisa.  The filename on the Lisa will
be something like
.I example/fromhex.text.
Then using the generic exec script on the Lisa, compile this Pascal
program and put the resulting binary on a Mac disk along with
MacTerminal.
.PP
At SUMEX our SUMACC disks also contain the
.I 
Resource Mover, Set File, Examine File, MacsBug, Disassembler,
.R
and
.I Disk 
.I Copy
utilities.  These are useful utilities supplied on the
.I MacMaster
disks that come with the Workshop.
.PP
You should now be able to follow the instructions under
.B Downloading
below to try out some of the programs in the VAX
.I test
directory.
.NH
Test Programs
.PP
The C test programs provided are:
.IP MacScrawl 2
A primitive text/drawing program that was used to test out
the Quickdraw and Event Manager routines.  Its commands are
single keyboard characters;  examine the source code before
trying to use it.  Try the 'm'agnifying lens to zoom in and out
on sections of the screen and/or the lens itself.  In one-to-one mode
there is some interesting stuff going on at the bottom of screen memory.
.IP Grow
This is a straight translation of the Pascal Grow program provided
in the Workshop.  Windows, events, menus, TextEdit, and
desk accessories are all exercised.  
As an exercise, you might runoff a listing of grow.c and grow.p.ws
(in the same directory) to compare how the Pascal was translated to C.
.I
Note a bug: 
.R
both the Pascal
and the C version apparently do not save TextEdit state when the
Notepad desk accessory is in use, resulting in weird behavior
with that accessory.
.IP Insane
This tests the SANE IEEE 80 bit floating point package and
numeric conversion.  Floating operations seem to average
about 1 millisecond (well you can't say it isn't accurate...).
.NH
Typical Compilation Cycle
.PP
Examine the Makefile and *.rc (resource compiler input)
files in the test directory.
The makefile typically looks something like:
.DS
.I
cc68 \-m grow.c
rmaker grow.rc
tohex grow.dl
.R
.DE
.PP
Cc68 compiles, assembles, and loads the C program onto a file
called
.I b.out.
Next the resource maker (sometimes called the resource compiler)
reads the file grow.rc.
This file directs rmaker to read the binary b.out and combine it
with some hex icon information in grow.rc.  The resulting
output, which would be directly executable on the Mac, is
left in the file grow.rsrc.  (rsrc stands for 'resource', and
is the same suffix convention that is used on the Lisa).
.PP
Finally, since the current download scheme uses 
MacTerminal, which only understands printable characters,
the trivial program
.I tohex
converts this binary info into hex nibbles that MacTerminal
can handle.  It also adds a checksum for security.
The resulting grow.dl (for 'download') file is then
downloaded to the Mac using MacTerminal, and reconverted to 
binary, using fromhex.
.PP
From time to time, you will also want to 
.I lint
your sources to ensure proper matching of argument and data
types.  For example:
.I
lint grow.c -lmac
.R
.NH
Current State of Downloading
.PP
After obtaining a download file (e.g. grow.dl) from the compilation
cycle, you download it as follows:
.IP [1] 4
Launch MacTerminal.  When it comes up, type 
.I 
cat grow.dl.
.R
The file will scroll by on the screen and at the same time MacTerminal
will be saving the 'lines off the top' into a file.
If you were previously using MacTerminal before the downloading
step, then you will want to select the
.I
clear lines off top
.R
menu command before catting the file.  Alternately you could
turn on the 
.I
File Transfer / Remember Lines off Top
.R
mode just before the cat.
Personally, I use another terminal for my VAX work and I throw
an RS232 switch just before I invoke MacTerminal and cat the file.
.IP [2]
With early versions of MacTerminal, the output file is called
.I TermCache.
The latest version of MacTerminal places this output into the data
fork of your MacTerminal configuration file.  For example
if my configuration file is called 'C', the baud rate settings and
so forth are held in the resource fork of C, while the 'scroll-off'
is placed in the data fork of C.
.IP [3]
After the cat is complete, hit a few more CRs, to ensure that
the lines are 'scrolled off the top' and thus saved.  (There's
a shell file in
.I test/mcat
to do this if you're lazy).
Then exit MacTerminal.
.IP [4]
The fromhex program takes its input from a file called 'C' and
places the output on 'C prog'.  If the output from MacTerminal
is not already named 'C', select it with the mouse and type 'c'.
This will change the name (case is not important).
Now launch 'fromhex'.  If all works correctly it will read 'C'
and create an executable 'C prog'.  If the checksum fails
(very rare), it will beep at you, which tells you to try
the transfer over again with MacTerminal.
.IP [5]
Finally (phew!) you can launch 'C prog' and it will execute.
Rename 'C prog' to something else if you want to keep it around
and run fromhex some more.
If your program uses a special icon (as do the samples provided),
a strange feature of the 'finder' requires that the 'bundle'
bit be set at least once on one of these binaries.  You
can use the 'Set File' program for this.  After finder
caches the icon in it's 'DeskTop', further bundle bits are
not needed.
.NH
Future State of Downloading
.PP
Needless to say, the above sequence is less than speedy.
Here are some other possibilities:
.PP 
The next version of MacTerminal will have a working Modem7
file transfer mode.  I have heard that there are UNIX versions
of this floating around (where?)  Martin Haeberli also tells
me that this new version will recognize special 'control codes'
in the data stream, if in 'Macintosh' mode.  These codes allow
the data stream to be directed to either the data or resource
fork of the destination Mac file.  Thus the UNIX modem7 could
have a switch for directly transfering the *.rsrc file into
a resource file on the Mac.  'tohex' and 'fromhex' could
be tossed.
.PP
Martin says that modem7 and MacTerminal are somewhat inextricably
bound, thus putting another protocol (such as Kermit) into
MacTerminal would not be easy.  However, what about this:
the C version of Kermit already exists and with a moderate
amount of effort, a dumb terminal emulator could be added to
it.  This would give us our own terminal emulator to 
customize to death, and allow Kermit access (which seems
to be more common in Arpa land).  Any volunteers?
.PP
When we get our act together here at SUMEX we plan to
start working in ernest on our MacEther file server.
In this case you would simply click open the server disk
icon and launch the program.  Current SUMEX priorities
are preventing me from continuing work on this at the moment.
.NH
Toolbox Programming
.NH 2
Argument Passing
.PP
When using
.I
Inside Macintosh
.R
to program in C, you must do a mental translation of the
Pascal calling conventions into corresponding C conventions.
They are really quite straightforward and even if you goof
up, lint will warn you.  
Take a look at the sample programs to get the hang of it.
Remember that a Pascal VAR, means a variable passed by
reference (address).
Here are the conventions:
.PP
When passing a structure or string, pass its address.
Pointers or handles are passed the same as in C (by value).
If Pascal expects a VAR, pass its address (if it's 
a structure or string, you've already 
converted that to an address (rule above)).
.PP
SUMACC also does automatic translation for 'integer'
and 'string' formats during Toolbox calls.  The default
integer in Pascal is a short, while C assumes it is a long.
Pascal strings are not null terminated and instead begin
with a byte count.
Some further implications of this mechanism for strings
are discussed in a section below.
.NH 2
Handle Dereferencing
.DS
The Pascal notation
.I
hTE^^.viewRect := pRect;
.R
is translated as
.I
(*hTE)->viewRect = pRect;
.R
.DE
.NH 2
Pascal Bird-Nest Soup
.PP
Compare test/grow.c with test/grow.p.ws.  Notice how the C version
can use many less nesting levels than Pascal by proper use of
.I
break, continue, 
.R
and
.I return
statements.  (In my opinion) this greatly improves the readability
and understanding of C programs.
C programs also allow much easier setup of initialized global
data and strings.  Part of the reason 'resources' are so
common in the Pascal example programs, is that they allow
an 'easy' way for Pascal programs to access initialized data.
Of course this must be tempered with the fact that these resources
must be named and numbered in another file and introduce another
level of indirection in understanding a program listing.
The plus side to resources is that they allow easy language
translation of your program, but how many of the programs you
write will have that wide a distribution?  If source is available
you could achieve a similar affect by placing your language
dependent strings in an ifdef'ed section or include file.
.NH 2
String Utilities
.PP
Normally on Toolbox calls, the routine
.I mactrap.s
converts automatically
between the C string convention
and the Pascal strings expected.  This occurs both
on passing the argument via the function call, and on string
VARs returned.
Thus in 99% of the cases you need do nothing special for strings.
However occasionally a Pascal string is embedded in a Toolbox
structure or a something similar.
In such cases there are these functions to help out (see test/grow.c
for an example call and lib/strconv.s for more detailed info):
.IP c2pstr 8
This converts a C to Pascal string in-place by shifting the C string
down one position and inserting a byte count at the beginning.
.IP p2cstr
This is the converse operation of converting a Pascal to a C string;
the byte count is removed and a trailing zero byte added.
.IP isapstr
This is a function;  it simply negates its argument, which is
a string pointer.  If passed to a toolbox routine that expects
a string, this negative pointer will override the default
C to Pascal string conversion.  In effect the function states 'this
argument is-a Pascal string'.
.NH 2
Heap vs. C Bss
.PP
Uninitialized globals in C are placed in an area called 'bss'.
In the current implementation, bss is reserved by appending
that amount of trailing zero bytes to the CODE resource.
(The Mac segment loader has no convenient mapping for
a bss notion contiguous to text/data;  sorry).
Thus you can use uninitialized globals as normal, but if you
have any truly large structures (over a few hundred bytes), you
should call the Toolbox routines 
.I NewPtr
or
.I NewHandle
to get piece of the heap,
and place the pointer or handle to that area in a global variable
instead.  This is actually a common C coding practice on
UNIX, using the 
.I malloc
routine there.
.NH 2
Pascal Toolbox Calling on C Routines
.PP
Yes this does happen (rarely).  For an example see test/grow.c in the
routines ScrollUp, ScrollDown.  Basically your C function must
call an assembly helper (getpargs) to fetch the Pascal arguments.
.NH 2
Floating Point
.PP
See test/insane.c for examples of SANE usage.  However you may
be better off with the fixed point arithmetic provided by
.I
FixRatio, FixMul, FixRound 
.R
discussed in the Toolbox Utilities
section of Inside Mac.
.PP
The MIT C compiler we are using also has its own built-in
floating point formats and library routines (in libc.a),
but we have no experience with these.
They are certainly not the IEEE standard.
.NH 
Compiler Sources
.PP
The normal distribution contains only sources for the code we
have written here at SUMEX.  Since the compiler is based on
the Bell Labs (Johnson) Portable C Compiler, we must be careful
about distributing copies of this.  
It's also unclear to me what good the compiler/assembler/loader
will do for you, since it's a large and somewhat crufty
amount of code.
As an interim policy we
will make these sources available to other Universities if there
is enough interest.
However don't ask unless you plan some active
development in this area.
.NH
Currently Unimplemented
.PP
Overlays;  MacPrint interface and linkage;  Graf3D (but see
lib/TODO for a hint on how to convert this).
.NH
Freeware
.PP
If you think sharing stuff like this is a good idea, then I
encourage you to make your own projects available to the
info-mac community.  Post a note to info-mac and tell folks
how to FTP the program from your site;  alternately SUMEX
would be glad to archive your programs for FTPing in our
info-mac directory.