sean@oddjob.UChicago.UUCP (Sean Casey) (09/02/84)
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.rsrc >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.