#lisa workshop

Tonight's project: learn how to write code that runs on Apple's LisaOS. In this piece, I am using Lisa Office System 3.1, with Workshop 3.0.

As you can imagine, there hasn't been any kind of documentation on this in decades, so it was all learned through painful trial and error, and scouring old manuals for information. Fun!

Getting Started

Lisa's development environment is Workshop, though insert the disks into your running Lisa[emulator] and you'll find they can't be read by the OS - this is no mistake: you have to boot from the Workshop disk 1 and install it to your hard disk, effectively creating a dual-boot environment.

Boot into Workshop, and you're greeted with a text-based UI. Virtually everything you do in this environment works like this (except for the text editor, thankfully).

You will have to become very acquainted with these tools to get your own code up and running. Pressing a letter on the keyboard will open the corresponding named option onscreen. Open Edit with 'E'.

The Sample App

Let's write a simple 'Hello World' Pascal app - just about the only program code I can fit in a single screenshot. In Edit's File menu, choose 'Tear Off Stationery', and hit enter for the next prompt. Use the following code, then File -> Save & Continue (name it LisaTest - the .TEXT extension is automatically added).

Exit the editor to drop back to the shell.

Compiling

Next up, the Pascal compiler! Press 'P'. Type the name of the file (extension automatically implied), give it nothing for a list file, and you can leave the output file (.OBJ) as-is. If all goes well, you should get the following.

Linking

Now, you have an object file, but to run the app you will need to link it first. Press 'L' at the Workshop prompt (it's a hidden option) to enter the Linker. Here's where it gets complicated - not only do you have to pass it your OBJ file, but you also need to know which libraries to link (good luck finding any documentation online!). The Lisa Pascal 3.0 Reference Manual has a complete listing & description of all the Workshop files & libraries as an appendix if you run into issues finding the right libraries to link. In this example, you need three: 'sys1lib', 'iospaslib', and 'qd/support'.

Completing the Installation

There is some bad news; the qd/support (QuickDraw) interface is not installed on the hard disk by default. I recommend copying all the files from disks 7-9 using the FILE-MGR.

This is a convoluted process; you need to insert each disk, copy everything, then open the Editor to use the File menu option to eject the disk (!).

The copy syntax is as follows: the from option should be '-#13-' and the to option should be '='.

This will then ask you to Y/N every single file on the disk and then start the copy.

After each disk has finished copying, eject it from the Editor. Once you have everything, you're ready to continue.

Back to Linking!

Give Linker the input as shown above (note the output file name - you don't want it to accidentally overwrite your compiled Pascal OBJ), and you should end up with a compiled, runnable app.

Running

Let's test this theory!

Press 'R' at the Workshop prompt, give it your app's name (LisaTestApp, in this case - and the .OBJ extension is implied), and hit enter.

Success! You now have a running app that uses QuickDraw to display text. Getting this installed to the Office System (the regular LisaOS) is a whole other hassle.

Installing

You need to copy your LisaTestApp.OBJ to {T*}Obj (replace * with any high number, this is your 'Tool' number - you don't want to overwrite/conflict with any existing Tool numbers - system or otherwise). In my case, {T1337}Obj, of course.

From the Run prompt, use InstallTool. This is pretty straightforward, and should be easy to navigate. Give it your chosen Tool ID and it will do the rest.

With that, quit & reboot into Lisa Office System. You should have a new icon on your hard drive, that, when double-clicked, runs your code!

MASSIVE DISCLAIMER

…and at this point, you realize your app has locked up, and the only thing you can do is reboot LisaOS. Welp.

Lisa's Office System environment needs a lot more boilerplate code to actually make a running app, with windows and menus. This is so much more complicated that it's well outside the scope of this piece. There is a very helpful set of tutorials and labs (Lisa ToolKit Self-Paced Training, published by Apple) from 1984 that will help you get up and running with a ToolKit stationery app. There's also plenty of QuickDraw sample code on the Workshop drive from which you can learn and explore.

Sadly, as I mentioned at the start, virtually no documentation for any of this exists online. If you're lucky (like I was), you might be able to glean enough information from ancient PDFs and manuals.

As a parting gift, I leave you with some QuickDraw sample code ported to a working object-oriented Pascal (Clascal) ToolKit app in Lisa Office System:

UPDATE