Uli's Web Site
An Introduction to SuperCompiler
One of the projects I have on this site is a compiler for scripts written in SuperTalk, the programming language of SuperCard. It's simply called SuperCompiler. It's not really a compiler in the sense that it generates machine code itself. Rather, it translates SuperTalk into a form of C++, which is then handed off to Apple's compiler to take care of actually generating the code.
This is a short tutorial. To follow along, you will first of all need SuperCard 4.6 or later, and Mac OS X 10.4.7 or so. You will also need to install the developer tools, which you can find on one of your system CDs as an "Xcode Tools" installer. However, make sure you have a fairly new version (2.3 or later), or it won't work correctly. If you don't have one, you can download one for free from Apple's developer web site, but you may have to sign up as a free "ADC Online" member before you can see the link.
Once you've got all that, go to the SuperCompiler link above and download SuperCompiler. It's a SuperCard project that you can just run by double-clicking the "SuperCompiler.sc45" project file. (yeah, I know it's a little on the complicated side, but that's why this is a free pre-release and not a finished product)
What is what?
When you open SuperCompiler, you'll see a large text field. This is where you'll write the SuperTalk script that you want to compile. Below that is a text field labeled "Destination Project" with a "Choose..." button next to it. SuperCompiler compiles your script into an "XCmd" or "XFcn" ("external command" or "external function"), which is a sort of SuperCard plugin that you can call just like any other SuperTalk handler. These plugins are usually written in a complicated programming language like C or C++ and can do things you can't do in SuperTalk. You can find a number of XCmds and XFcns in the SuperCard Help's "XTend" window, or download lots of others from externals.net.
Usually, you have to copy XCmds and XFcns into your project using the "Resource Manager" from the "Utilities" menu. But SuperCompiler is nice and allows you to specify a SuperCard project into which you want to copy your new compiled script. So, create a new, empty SuperCard project and then use the "Choose..." button to tell SuperCompiler to copy your script there.
Writing your first script
So, now that you have a project to put the script in, you'll need a script to compile. We'll start out simple: Choose "New Script..." from the "SuperCompiler" menu in the menu bar (it may ask you to save any example script I left in the script field, you may wanna do that to look at it later to see what else you can do with SuperCompiler). It will ask you for a name for your new XFcn. Type in "Tutorial" (that is the name under which your new external will be saved on disk and under which you will be able to call it up from the SuperCompiler menu). You'll get a pretty empty field with only a line or so of comment. Type the following SuperTalk script into the field:
function repeatACharacter whatChar, howOften put empty into myText repeat with x = 1 to howOften put whatChar after myText end repeat return myText end repeatACharacterThis is a simple function that you could run in SuperCard. Now click the "Create XCMD" button. A new window titled "Log Window" will open. Depending on how fast your Mac is, you might get the spinning rainbow cursor now, that's OK. After a while, it will spit out some text documenting what it did. In my case that is:
Starting XCMD creation on Samstag, 2. Dezember 2006 at 21:48:40 Uhr HyperCompiler 0.1 HyperTalk-to-C-compiler by M. Uli Kusterer (c) 2006, all rights reserved. Created on Nov 22 2006 at 23:44:44 Tokenizing file "/Users/witness/Programming/HyperC/SuperC Folder/SuperC_Support/tempScript.hc"... Parsing file "/Users/witness/Programming/HyperC/SuperC Folder/SuperC_Support/tempScript.hc"... Using template "xcmd". Handing script off to GCC... Post-processing output file... Output file is: repeatacharacter.bundle Finished successfully. Copied output file to resource. Deleted output file. Ended XCMD creation on Samstag, 2. Dezember 2006 at 21:49:07 UhrIf you made a typo, you will get script errors reported in that list. E.g. if you wrote "end repeatACharacters" with an "s" at the end by accident, you'd see:
... Tokenizing file "/Users/witness/Programming/HyperC/SuperC Folder/SuperC_Support/tempScript.hc"... Parsing file "/Users/witness/Programming/HyperC/SuperC Folder/SuperC_Support/tempScript.hc"... Error in line 10: error: Expected "end repeatacharacter" here, found repeatACharacters. Error copying bundle: Parameter 3 must contain a resource ID or name. Ended XCMD creation on Samstag, 2. Dezember 2006 at 21:51:48 UhrThe important part here is the line starting with "Error in line 10:". Click that line and it will select the offending line in your script so you can fix it. Ignore the errors below that ("Error copying bundle:" -- SuperCompiler just got confused after the first error (which prevented it from creating a working XCmd) and complained that there's no XCmd to copy).
Okay, so since you of course didn't make any typos, close the Log Window. You'll see that SuperCompiler has already opened the destination project you created. If you open up the "Resource Manager" and choose your destination project from the popup menu, you'll see a new entry: XFcn repeatacharacter. Note how SuperCompiler automatically took the name of the first handler and named the XCmd after it. Furthermore, SuperCompiler realized that the first handler is a function, and so created an XFcn, not an XCmd.
Close resource manager again and create a new button. Open the script editor for it and copy the repeatACharacter script into it, but rename the handler to repeatACharacterST (for "SuperTalk"). Then write a new handler:
on mouseUp put the ticks into start1 get repeatacharacter("-",10000) put the ticks into start2 get repeatacharacterST("-",10000) put the ticks into endTime answer "XFcn took:" && start2 -start1 &return& "SuperTalk took:" && endTime -start2 end mouseUp
When you now click the button, repeatACharacter will be run twice to produce 10000 dashes. The difference being that the second will run as a regular SuperTalk script, while the first will use the XFcn we just compiled. You'll notice that the XFcn will be slightly faster. If you don't, try adding one or two zeroes to the end of the 10000.
Neat, huh? You didn't do anything differently, but already your script runs faster. The difference isn't that big for most scripts, but when you have scripts that do number crunching or text manipulation in loops, HyperCompiler may yet make the difference between an instantaneous return value or a half-second wait.
You can also have additional handlers in your script, but note that your SuperTalk scripts will only see the first one. So, your first handler can call any other handler in the XCMD that comes below it, but SuperCard can only see the first handler.
This concludes our first little tour of SuperCompiler. If you're interested in finding out more about it, you can choose the "Help" menu item from the "SuperCompiler" menu to find out more about the cool things SuperCompiler can do. And if something in the help isn't clear, feel free to let me know and I might just write another tutorial. If you have questions about this tutorial, feel free to leave a comment below.
Created: 2006-12-02 @797 Last change: 2017-03-30 @645 | Home | Admin | Edit|
© Copyright 2003-2017 by M. Uli Kusterer, all rights reserved.