While dealing with editing my code in TextMate and uploading that to the GS emulator, certain things just begged for automation. Nothing too fancy, just some helpful utilities I have bundled into a framework of sorts. I call it the APW-ORCA/M Framework for MacOSX. It creates and manages projects written in ORCA/M assembly tailored for the AppleIIgs on MacOSX.
Download it: (AWPFrameWork1.1.tar.gz).
I have apw_projects designated as my Apple IIgs assembly language folder so I would put APWFrameWork1.1.tar.gz in that folder, then change directory to that folder and issue a “tar -xzf APWFrameWork1.1.tar.gz”. This will install the framework. You can then delete the tar file “rm APWFrameWork1.1.tar.gz” to save space.
You’re ready to go, first thing is to read the _README file. That will show you how to use the framework properly.
Additionally __LIBRARY/APW-ORCA:M.tmbundle is provided, Click to install this assembly language environment bundle to TextMate. It provides color coded syntax which makes editing APW sourcecode much easier.
Suggested TextMate settings:
Choose “Sunset” theme.
Set TAB SIZE = 15
Set Preferences/Advanced:LineEndings to CR (Mac OS Classic).
The macro generator in the framework is especially handy for generating the macro files and way easier to use than the MACGEN method provided in APW. The libraries are as up to date as possible, including macros for Marinetti. Included as well are some program templates that make the most basic desktop application. Additional tricky or painful templates for popular functions will be included in future releases.
This framework is written in Perl because I am old school and I have been writing in Perl for more than 15 years. I could have made it in PHP or Ruby but I’m better and quicker writing Perl… the results all wind up the same no matter which high level language you use. By the way… The underlying same-ness of languages is best viewed and understood from the assembly side of things.
I use this framework exclusively for all my IIgs programming projects and have found no bugs, but I’m sure someone out there will find some, it always happens.
As a final thought… If you have been reading along in these postings so far and don’t have APW or ORCA/M, squeeze out a couple bucks and get it here: (https://store.syndicomm.com/) I’m sure “Sheppy” will be thrilled to send you a copy. You can get all the manuals there as well.
Where do we start… Probably the best place is the tools and information you would need to start programming. You could blow the dust off your old IIgs and start there but you’re a modern homo sapien and probably have a gig or better machine sitting in front of you. The IIgs mainly ran at 1 megaherts, 2.8 tops and frankly is a bit slow for this type of task. I do my assembly language programming on a modern Mac mini, more than fast enough for the task. Back in the day much work on the IIgs was actually done on the Mac, you will find the two very similar in many ways.
I use the Sweet16 Apple IIgs emulator by Eric Shepard for the IIgs portion of things. This emulator has no drawbacks as far as I can see and is really a brilliant implementation. I use the Apple IIgs Programmers Workshop (APW) and AppleworksGS in the emulator. No other IIgs software is really needed and AppleworksGS is only used for graphics. All other software is either Mac or Windows based. I have not found a place where you can buy a copy of AppleworksGS, I use my original copy purchased in 1988.
On the Mac I have the Sweet16 emulator installed as well as Parallels which runs Window XP. The only thing I use Windows for is to run a 65816 disassembler I found on the web called D816. It’s not the best one I have ever seen but with some coaxing, it produces useable source code segments. There are basically two Mac applications I use in my process, TextMate and HexEdit. Click here for a complete listing of the programming environment.
You may have noticed that I have disassembler capabilities in the environment which usually is not needed for regular programming but, in working with an old system like the Apple IIgs many times I want to upgrade existing software and I don’t have or have lost the source code. The techniques for disassembly are probably just as important for me as is straight forward programming.
With all the hardware in place it’s on to the reference documentation which should be as comprehensive as possible. Most of the documentation is still available from syndicomm.com but be prepared to get some 3 ring binders because the reference manuals are only available in 3 hole punched, 2 sided xerox copy form these days. Finding some real old manuals on eBay or Amazon may be preferable or digging through an old timers documentation stash if you know one.
Although this development environment is on modern systems using emulation, you still should have a real Apple IIgs on hand for operational confirmation. There’s nothing like seeing your work running on the real deal. I have a couple machines on hand for these purposes, all Woz’s and they are just too cool for words. It makes people do double takes when they visit seeing an array of computers, some my development machines and some my play machines and some LINUX and Windows machines. Having the odd Apple II, +, C or E is fun too. Fortunately I never throw things out and over the past 30 years I have accumulated a virtual museum of great old equipment.
That’s about all for the preparation so next time we will get down to actually doing something with all this stuff.
Next post – Chapter 2: Dealing with files