A Guide to Legacy Mac Emulators

Last fall I wrote about the collaborative technical/scholarly process of making some ’90s multimedia CD-ROMs available for a Cinema Studies course on Interactive Cinema. I elided much of the technical process of setting up a legacy operating system environment in an emulator, since my focus for that post was on general strategy and assessment – but there are aspects of the technical setup process that aren’t super clear from the Emaculation guides that I first started with.

That’s not too surprising. The tinkering enthusiast communities that come up with emulators for Mac systems, in particular, are not always the clearest about self-documentation (the free-level versions of PC-emulating enterprise software like VirtualBox or VMWare are, unsurprisingly, more self-describing). That’s also not something that to hold against them in the least, mind you – when you are a relatively tiny, all-volunteer group of programmers keeping the software going to maintain decades’ worth of content from a major computing company that’s notoriously litigious about intellectual property….some of the details are going to fall through the cracks, especially when you’re trying to cram them into a forum post, not specifically addressing the archival/information science community, etc. etc.

In particular, while each Mac emulator has some pretty good information available to troubleshoot it (if you’ve got the time to find it), I’ve never found a really satisfying overview, that is, an explanation of why you might choose X program over Y. That’s partly because, as open source software, each of these programs is *potentially* capable of a hell of a lot – but might require a lot of futzing in configuration files and compiling of source code to actually unlock all those potentials (which, those of us just trying to load up Nanosaur for the first time in 15 years aren’t necessarily looking to mess with). Most of the “default” or recommended pre-compiled Mac/Windows versions of emulators offered up to casual or first-time users don’t necessarily do every single feature that the emulator’s front page brags about.

So what really is the boundary between Basilisk II and SheepShaver? Why is there such a difference between MacOS 9.0.4 and 9.1? And what the hell is a ROM file anyway? That’s what I want to get into today. I’ll start with the essential components to get any Mac emulation program running, give some recommendations for picking an emulator, then round it out with some installation instructions and tips for each one. (You can jump right to an app with this Table of Contents:

What do I need?

An Emulator
There are several free and open-source software options for emulating legacy Mac systems on contemporary computers. We’ll go over these in more detail in a minute.

An Operating System Installer
You’ll need the program that installs the desired operating system that you’re trying to recreate/emulate: let’s say, for example, Mac OS 8.5. These used to come on bootable CD-ROMs, or depending on the age of the OS, floppy disks. If you still have the original installer CD lying around, great! You can still use that. For the rest of us, there’s WinWorld , providing disk image files for all your abandonware OS needs.

A ROM File
This is the first thing that can start to throw people off. So you know your computer has a hard drive, where your operating system and all your files and programs live. It also has a CPU, central processing unit, which is commonly analogized to the “brain” of the computer: it coordinates all the different pieces of your computer, hardware and software alike: operating system, keyboard, mouse, monitor, hard drive (or solid state drive), CD-ROM drive, USB hub, etc.  etc.  This ensures your computer has at least some basic functionality even if your operating system were to get corrupted or some piece of hardware were to truly go haywire (see this other post). But the CPU itself needs a little bit of programmed code in order to work – it has to be able to both understand and give instructions. Rather than stored on a hard drive like the operating system, which is easily writable/modifiable by the user, this crucial, small central piece of code is stored on the CPU on a chip of Read-Only Memory (the read-only part is why this sort of code is often called firmware rather than software). That’s your ROM file. If the whole goal of an emulator is to trick legacy software into thinking it’s on an older machine by creating a fake computer-inside-your-computer (a “virtual machine”), you need a ROM file to serve as the fake brain.

This is trickier with Mac emulation than it is with Windows/PC emulation. The major selling point of Windows systems is that they are not locked into specific hardware: there are/have been any number of third-party manufacturers (Dell, Lenovo, HP, IBM, etc etc) and they all have to make sure their hardware, including the CPU/ROM that come with their desktops, are very broadly compatible, because they can never predict what other manufacturer’s hardware/software you may be trying to use in combination. This makes emulation easier, because the emulating application can likewise go for broad compatibility and probably be fine, without worrying too specifically about *exactly* what model of CPU/ROM it’s trying to imitate (see, for example, DOSBox).

Not so with Mac, since Apple makes closed-box systems: the hardware, OS, software, etc., are all very carefully designed to only work with their own stuff (or, at least, stuff that Apple has pretty specifically approved/licensed). So setting up a Mac emulator, you have to get very specific about which ROM file you are using as your fake brain – because certain Apple models would have certain CPUs, which could only work with certain operating system versions, which would only work with certain versions of QuickTime, which would only play certain files, which would………

That sounds exhausting.

It is.

Wait, if this relies on proprietary code from closed-box systems… is this legal?

Well if you got this far in an article about making fake Macs before asking that, I’m not so sure you actually care about the answer. But, at least so far as my knowledge of American intellectual property law goes, and I am by no means whatsoever an expert, we are in gray legal territory. You’re definitely safest to extract and use the ROM file of a Mac computer you bought. Otherwise we’re basically making an intellectual property fair use case here – that we’re not taking any business/profit from Apple from using this firmware/software for personal or educational purpose, and that providing emulation for archival purposes (and yes, I would consider recovering personal data an “archival” process) serves a public good by providing access to otherwise-lost files. The (non-legal) term “abandonware” does also exist for a reason – these forums/communities are pretty prominent, and Apple’s shown no particular signs recently of looking to shut them down or stem the proliferation of legacy ROMs floating around.

Of course, be careful about who and where you download from. Besides malware, it’s easy to come across ROM files that are just corrupted and non-functional. I’ll link with impunity to options that have worked for me.

[Also be advised! Files made from video game cartridges – SNES, Game Boy, Atari, Sega Genesis, the like – are *also* called ROM files, since game cartridges are also really just pieces of Read-Only Memory. Just searching “ROMs” is going to offer up a lot of sites offering those, which is very fun and all but definitely not going to work in your Mac emulator]

So how do I pick what ROM file and emulator to use?

That’s largely going to depend on what OS you’re aiming for. There are four emulators that I’ve used successfully (read: that have builds and guides available on Emaculation) that together cover the gamut of basically all legacy Mac machines: Mini vMac, Basilisk II, SheepShaver, and QEMU.

As I mentioned at the top, a confusing aspect is that many of these programs have various “builds” – different versions of the same basic application that offer tweaks and improvements focused on one particular feature or another. The most stable, generic version that they recommend for download might not actually be compatible with *every* ROM or operating system that the emulator can theoretically handle (with a different build).

In hunting down ROM files, you’ll probably also come across ROMs listed, rather than from a particular Mac model, as “Old World” or “New World”. These essentially refer to the two broad “families” of CPUs that Apple used for Macs before moving to the Intel chips still found in Macs today: generally speaking, “Old World” refers to the Motorola 68000 series of processors, while “New World” refers to the PowerPC line spearheaded by “AIM” (an Apple-IBM-Motorola alliance).

New World and Old World ROMs can be a good place to start, since they are often taken from sources (e.g. recovery discs) more broadly aimed at emulating Motorola 68000 or PowerPC architecture and therefore could potentially imitate a number of specific Mac models – but don’t be too surprised if you come across a software/OS combination that’s just not working and you have to hunt down a more specific ROM for a particular Mac brand/model. We’ll see an example of this in a moment with our first emulator.

If you are currently using macOS or iOS, you can find some wonderfully detailed tech specs on every single piece of Mac hardware ever made using the freeware Mactracker app. Picking an exact model to emulate based on your OS/processor needs can help narrow down your search.

So with that in mind, let’s cut to the chase – moving chronologically through Mac history, here are my recommendation and install tips:

Mini vMac

Recommended:

Mini vMac is an easy-to-setup (but thereby probably not the most robust) emulator for black-and-white Motorola 68000-based Macs. While it’s eminently customizable if you dig into the source code (or pay the guy who makes it at least $10 for a year’s worth of by-request custom setups – not a bad deal!!), the “standard variation” of this app that the Mini vMac page encourages you to download for a quick start quite specifically emulates a Macintosh Plus. The Macintosh Plus could run Mac System 1.0 through 7.6.1 – but the System 7.x versions frequently required some extra hardware finagling, so I’d recommend sticking with Mini vMac for Systems 1.0 through 6.x.

Also, while a generic Old World ROM *should* work since Mac Pluses had 68000-series CPUs, I haven’t had much success with those on the standard variation of Mini vMac. Look for a ROM file specifically from a Mac Plus instead (such as the one in the link above, to a very useful GitHub repository with several ROMs from specific Mac models).

Installation:

  1. Download the standard variation build for your host operating system (OSX, Windows, etc.)
  2. Download a bootable disk image for your desired guest OS – System 1.x through 6.x (note these will probably be floppy disk image files, either with a .dsk or .img file extension).
  3. Download the Mac Plus ROM, rename it to “vMac.ROM” and place it in the same folder as the Mini vMac application.
  4. Double-click on the Mini vMac application to launch. You should hear a (very loud) startup beep and see a picture of a 3.5″ floppy with a blinking question mark on it – this indicates that the emulator has correctly loaded the ROM file but can’t find a bootable operating system.
  5. Drag the disk image for your operating system on to the Mini vMac window. If it’s a complete, bootable disk image, your desired operating system environment should appear!
  6. From there, it’ll depend what you’re doing – if you’re just trying to run/look at a piece of software from a floppy image, you can just drag and drop the .img or .dsk into the Mini vMac window and it should appear in your booted System 1.x-6.x environment.If you want to create a virtual “drive” to save your emulated environment on, you can create an empty disk image with one of the next two emulators on this list or the dd command-line utility if you’re on a Mac/Linux system (note: creating a Blank Image through a contemporary version of macOS’ Disk Utility won’t work):


    [cc lang=”Bash”]$ dd if=/dev/zero of=/path/to/image.img bs=512 count=1000[/cc]

    will make a 512 KB blank image (512 bytes was the traditional size for floppy disk “blocks”).You can increase the count argument to however large you want, but be warned that early file systems had size limitations and at some point operating systems and software like the classic Mac systems might not recognize/work with a disk that’s too large. Once you have a blank disk image, you can just drop it into a Mini vMac window running a legacy OS to format (“initialize”) it to Apple’s old HFS file system and start installing software/saving files to it.Generally speaking though, a lot of apps and files from this era ran straight off of floppies, so if you’re just looking to run old programs without necessarily saving/creating new files, dragging and dropping in a system disk and then your .img or .dsk files should just do the trick!

Basilisk II

Recommended:

Basilisk II is another well-maintained Motorola 68000 series emulator. But whereas Mini vMac is primarily aimed at emulating the Mac Plus, Basilisk can either emulate a Mac Classic or a Mac II series model (hence “Basilisk II” – there never was a “Basilisk I”), depending on the configuration/build and ROM file used. As with Mini vMac, this might not be clear, but the precompiled configurations of Basilisk for Mac and Windows offered up on the Emaculation forums – which is where the Basilisk II homepage sends you – specifically offers the latter. So while you may see info that Basilisk II can emulate all the way from System 0.x through 8.1, the version you’re most likely going to be using out-of-the-box can probably only handle the more limited range of System 7.x through 8.1 (the targeted range for the Mac II series).

Note though: this was a kind of bananas era for Apple hardware when it came to model branding. So in terms of looking for ROMs, you can try to find something specifically labelled as being from a Mac II series machine – but you may also find success with a ROM file from a Quadra (largely the same as Mac II machines, but with some CPU/RAM upgrades) or a Performa (literally re-branded Quadras with a different software configuration, intended for consumer rather than professional use). In fact, the Performa ROM and Quadra ROMs on Redundant Robot’s site works quite well, so I’ve linked/recommended that above (the Performa one definitely supports color display, so that’s a good one). These have the benefit of emulating a slightly more powerful machine than the older Mac IIs – but just keep in mind what you’re doing. Your desired OS may install fine, but you may still encounter a piece of legacy software that is relying on the configuration and limitations of the Mac II.

Installation:

  1. Download the precompiled app for your host operating system from Emaculation (I’ll assume OSX/macOS here).
  2. Download a bootable disk image for your desired guest OS, from 7.x through 8.1 – I’ll use Mac OS 7.6.1 here as an example. Note this is right in the transition period from floppies to CD-ROM – so your images may likely be ISOs instead of .img.
  3. Download the Performa ROM from Redundant Robot and unzip it. It’s a good idea to put it in the same folder as the Basilisk app just to keep track of it, but this time you can put it anywhere – you’ll have the option to select it in the Basilisk preferences no matter where it lives on your computer (and you don’t need to rename it either).
  4. In the Basilisk folder, double-click on the “BasiliskGUI” app. This is where you can edit the preferences/configuration for your virtual machine:
  5. In the “Volumes” tab, click on “Create…”. We need to make a totally blank disk image to serve as the virtual hard drive for our emulated computer. Choose your save location using the file navigation menu, then pick a size and name for this file (something descriptive like MacOS7 or OS7_System can help you keep track of what it is). For System 7, somewhere around 500 or 1000 MB is going to be plenty. Hit “OK” and in a moment your new blank disk image will appear under the “Volumes” tab in preferences.
  6. Next select “Add” and navigate to the bootable disk image for your operating system. So, here we select and add the System 7.6.1 ISO file.
  7. The “Unix Root” is an option for Basilisk to create a “shared” folder between your host, contemporary desktop and your emulated environment. This could be useful later for shuttling individual files into your emulator later (as opposed to packaging and mounting disk images), but is not strictly necessary to set up right now. If you do choose to create and set up a shared folder right now, you have to type out the full file path for the directory you want you use, e.g.:
  8. Keep the “Boot From” drop-down on “Any” and the “Disable CD-ROM Driver” box unchecked.
  9. The only other tab you should have to make any changes on at this point are “Graphics” and “Memory/Misc”. For “Graphics”, make sure you have Video Type: “Window” selected. The Refresh Rate can be “Dynamic” so long as you’re on a computer that’s come out within…like, the last 10 years. The width and height resolution settings are up to you, but you might want to keep them accurate to a legacy resolution like 640×480 for accurate rendering of software later.
  10. In the “Memory/Misc” tab, choose the amount of RAM you want your virtual machine to have. 64 MB is, again, plenty powerful for the era. Again, you can always tweak this later if it helps with rendering software. Keep Mac Model ID on “Mac IIci (MacOS7.x)” (note: I’ve successfully installed System 7 in Basilisk using this setting and Quadra 900 ROM, so I think the desired operating system, rather than the Mac Model, might be the most important thing to keep in mind here). Also leave CPU Type on “68040”. Finally, use the Browse button to select the Performa ROM file you downloaded:
  11. At this point, you can hit “Save” and then “Start” at the bottom of the Basilisk Settings window…and you should successfully boot into the System 7.6.1 ISO! The desktop background even comes up with little optical discs to make sure you know you’re operating from a CD-ROM:
  12. The “disk is unreadable by this Macintosh” error is to be expected: this is the blank virtual drive that you created, but haven’t formatted yet. Choose “Initialize” and then “Continue” (you’re not wiping any data, because the blank disk image doesn’t have any data in it yet!!). You should get an option to name your new drive in System 7 – I generally like to name this the same thing that I named the disk image file, just to avoid confusion and make it clear (to myself) that this is just the same file/disk being represented in two different environments.
  13. Once that’s done, you should just be on the System 7 desktop, with two “drives” mounted in the top right: the Mac OS 7.6.1 ISO installer, and then your blank virtual drive. Double-click on the Mac OS 7.6.1 ISO drive and then the “Install Mac OS” program to start running the installer software.
  14. The System 7.6.1 installer in particular forces you to go through a README file and then to “update your hard disk driver” (you can just select “Skip” for the latter).
  15. For the “Choose a disk for installation” step, make sure you have selected the empty (but now formatted) virtual drive you named.
  16. From there you should be able to just run the installer. This copies over and installs the Mac OS 7 system from the ISO to your virtual hard disk!
  17. When the program has successfully run, you now quit out of Basilisk by shutting down the emulated System 7 machine. (Hint: this used to be in the “Special” menu!)
  18. You can now remove the System 7.6.1 ISO file from the Volumes list in Basilisk’s setting, so that every time you launch the software, it goes right into the System 7 environment now installed on your virtual drive. You can now also mount/add any other software for which you have an ISO or IMG file (CD or floppy, basically) by adding that file to Basilisk’s Volumes list and relaunching Basilisk!

SheepShaver

Recommended:

SheepShaver is a PowerPC Macintosch emulator, maintained by the same team/people who run Basilisk II – so you’ll find that the interface and installation process of using SheepShaver are extremely similar. Since we’re dealing with PowerPC architecture now, you’re going to need a New World ROM, or similar specific ROM (I’ve had general success pretending I’m using one of the blue-and-white Power Macintosh G3s).

You might notice that SheepShaver’s maximum installable-OS point is Mac OS 9.0.4 – even though yes, versions of Mac OS 9 existed above 9.0.4. This is because SheepShaver cannot emulate modern Memory Management Units (MMUs) – a particular advancement in CPU technology that we don’t need to get into too much right now (particularly since I don’t totally understand at the moment what it does). But the point is, Mac OS 9.0.4 was the last Mac operating system that could function entirely without a modern-style MMU. If you need Mac OS 9.1 or above, it’s time to start looking at QEMU – but, just speaking personally, I have yet to encounter a piece of software that was so specific to Mac OS 9.1-9.2.2 that it didn’t work in 9.0.4 in SheepShaver.

Installation:

  1. Download the precompiled app for your host operating system from Emaculation (I’ll assume OSX/macOS here).If you are using macOS Sierra (10.12) or above as your host OS:
    Starting with Sierra, Apple introduced a new silent “quarantine” feature to its Gatekeeper software, which manages and verifies applications you’ve downloaded through the App Store or elsewhere. I can bet that at one point or another you’ve gone to the Security & Privacy section of your System Preferences to allow apps downloaded from “identified developers” or even to just let through one troublesome app that Gatekeeper didn’t trust for whatever reason. Perhaps you even remember the old ability to allow apps downloaded from “Anywhere”, which Apple has now removed as an option from the System Preferences GUI.As a result, some applications that you just download in a .zip file from a third-party (like the Emaculation forums) may not open correctly because it has been quietly “quarantined” by Gatekeeper, removing the permissions and file associations the application needs to run correctly. Obviously this is a strong security feature to have on by default to protect against malware, but in this case we want to be sure SheepShaver at least can pass through. Though you can’t do this in System Preferences anymore, you can pass apps individually through the quarantine using the following command in Terminal:[cc lang=”Bash”] $ sudo xattr -rd com.apple.quarantine /path/to/SheepShaver.app [/cc]
  2. Download a bootable disk image for your desired guest OS, from 8.2 through 9.0.4 – I’ll use Mac OS 9.0.4 here as an example. This is firmly in the CD-ROM era now so it should be an ISO file.Once you have downloaded and extracted the ISO file, you must “lock” the ISO in Finder. This is needed to trick the Mac OS 9 installer software into thinking it is really on a physical CD-ROM. You can do this by right-clicking on the ISO, selecting “Get Info”, then checking the “Locked” box:
  3. Download the New World ROM from Redundant Robot and unzip it. Put this in the same folder as the SheepShaver app itself and rename the ROM file so it is just named “Mac OS ROM” (spaces included, no file extension):
  4. Double-click on the SheepShaver app icon to launch the app. If the app has successfully found a compatible ROM in the same folder, you should see a gray screen with a floppy disk icon and a blinking question mark on it:

    (If no compatible ROM is found, the app will just automatically quit on launch, so you can troubleshoot from there).
  5. In the SheepShaver app menu at the top of your screen, select “Preferences” to open the settings menu, which happens to look pretty much just like the Basilisk II settings window.
  6. In the “Setup” tab, click on “Create…”. We need to make a totally blank disk image to serve as the virtual hard drive for our emulated computer. Choose your save location using the file navigation menu, then pick a size and name for this file (something descriptive like MacOS9 or OS9_System can help you keep track of what it is). For installing OS 9, again, somewhere around 500 or 1000 MB is going to be plenty. Hit “OK” and in a moment your new blank disk image will appear under the “Volumes” tab in preferences.
  7. Next select “Add” and navigate to the bootable disk image for your operating system. So, here we select and add the (locked) Mac OS 9.0.4 ISO file.
  8. For the “ROM File” field, click Browse and select your “Mac OS ROM” file. As long as the ROM file is in the same directory as the application and named “Mac OS ROM”, SheepShaver *will* read it by default, but it doesn’t hurt to specify again here (or if desired, you could select other ROMs here at this point for testing/troubleshooting).
  9. The “Unix Root” is an option for SheepShaver to create a “shared” folder between your host desktop and your emulated environment. This could be useful later for shuttling individual files into your emulator later (as opposed to packaging and mounting disk images), but is not strictly necessary to set up right now. If you do choose to create and set up a shared folder right now, you should type out the full file path for the directory you want you use, e.g.:
  10. Keep the options on “Boot From: Any” and leave “Disable CD-ROM” unchecked. Choose an amount of RAM you want your virtual machine to have. 512 MB was plenty powerful for the time, but you can futz with this potentially based on the requirements for the software you’re trying to run.
  11. For the “Audio/Video” tab, make sure you have Video Type: “Window” selected. The Refresh Rate can be “Dynamic” so long as you’re on a computer that’s come out within…like, the last 10 years. The width and height resolution settings are up to you, but you might want to keep them accurate to a legacy resolution like 640×480 for accurate rendering of software later. Make sure “Enable QuickDraw Acceleration” is selected and leave audio settings alone.
  12. Under the “Miscelleaneous” tab, select “Enable JIT Compiler”, “Allow Emulated CPU to Idle” and “Ignore Illegal Memory Accesses”. You can select the Mouse Wheel Function to taste. If you’re interested in getting networking working inside your virtual machine, in the “Ethernet Interface” enter the word “slirp” – otherwise, you can ignore this section.
  13. Hit “Save” to save these preferences and leave the settings window. You should be back at your blinking gray floppy. At this point, the only way to shut down the virtual machine and apply your new settings is to force-quit SheepShaver by pressing Control + Esc.
  14. Immediately double-click on the SheepShaver app again to relaunch. This time, you should boot into the Mac OS 9 installer CD! The desktop background should make it very clear you are booted into a CD installer:
  15. The “disk is unreadable by this Macintosh” error is to be expected: this is the blank virtual drive that you created, but haven’t formatted yet. Choose “Initialize” and then “Continue” (you’re not wiping any data, because the blank disk image doesn’t have any data in it yet!!). You should get an option to name your new drive in OS 9 – I generally like to name this the same thing that I named the disk image file on my host system, just to avoid confusion and make it clear (to myself) that this is just the same file/disk being represented in two different environments.
  16. If it hasn’t already opened automatically, double-click on the Mac OS 9 ISO drive and then the “Install Mac OS 9” program to start running the installer software.
  17. For the “Choose a disk for installation” step, make sure you have selected the empty (but now formatted) virtual drive you named.
  18. From there you should be able to just run the installer. This copies over and installs the Mac OS 9 system from the ISO to your virtual hard disk!
  19. When the program has successfully run, you can remove the ISO file from the mounted “Volumes” in SheepShaver’s preferences. Hit “Save” and then shut down the emulated machine to quiet SheepShaver (hint: the “Shut Down” command used to be in the “Special” menu on Mac OS desktop!!)
  20. Now, when you relaunch SheepShaver again, you should boot directly into your installed Mac OS 9 environment! As with Basilisk, you can mount floppy or CD-ROM images into your emulated desktop by opening SheepShaver’s Preferences and selecting the image files to Add them to your Volumes list (you’ll have to quit SheepShaver and relaunch any time you want to change/apply new settings, including loading new images!!)

QEMU

Recommended:

  • Mac OS 9.1 – Mac OSX (10.0-10.5)

QEMU is a generic, extremely flexible emulator/virtualization application. It can be theoretically configured to run all kinds of guest operating systems on all kinds of hosts, not just Macs; but the forum users at Emaculation have put a lot of work into assembling QEMU builds specifically capable of PowerPC MacOSX emulation, a processor/OS combination that has generally hounded and confounded the emulation community for some time.

As such, I’ll say up front this is definitely the roughest emulator to use, both in terms of the emulated system not running as smoothly as you’ll see with the other listed programs (audio, for instance, isn’t working unless you use an experimental build) and in that troubleshooting is going to be near impossible without a basic understanding of Bash scripting. (You *can* just follow exactly this guide or the Emaculation tips with a basic text editor like TextEdit, but especially given the fact that the forums are pumping out new builds on the regular, there’s no guarantee these will work/last very long).

The good news is – you don’t need a separate ROM file for this one! I assume the necessary code is just packaged into the provided QEMU builds rather than kept in a separate file. The Emaculation forums provide a few approved builds depending on what exactly you’re trying to do, but unless you’re trying to do some emulated networking (if you’re just a beginner here – not recommended), the first download link on that page is the one you should use. This will let you install any PowerPC OS from 9.1 up that you choose – for the purposes of this guide, I’m going to pretend I’m putting Mac OSX 10.1 “Puma” on a classic Bondi Blue iMac G3!

Installation:

  1. Download the precompiled build for your host system. For Mac systems, we’ll be using the first download in this forum post, although again, remember that you will not have audio with this build!! Feel free to explore some of the experimental versions once you have the process down.
  2. Unzip the QEMU folder and put your MacOSX install disc ISO into that same folder.
  3. Open the Disk Utility program. Hit Command+N (or go to File -> New Image -> Blank Image) to create a blank disk image for your virtual hard drive (we have now moved up far enough in time that Disk Utility can actually do all the proper formatting/partitioning here!)With the file browser navigate into the QEMU download folder and name your file something descriptive, like MacOSPuma. You will need at least 1.2 GB to install OSX 10.1, so I’d recommend making the blank image at least 2GB – note that Disk Utility makes you enter this number in MB! (so, 2000 MB)For “Format”, select “Mac OS Extended (Journaled)”. For “Encryption” select “none”, for “Partitions”, select “Single partition – Apple Partition Map” and for “Image Format” select “read/write disk image”.It will take a minute to create the blank disk image, but you should wind up with a file called “MacOSPuma.dmg” in your QEMU folder.
  4. In the downloaded folder there should be a file called “qemu.command”. Open this file with a plain text editor, TextEdit will do.
  5. Much of the text here is good, but we need to make a few substitutions. Namely, we need to attach a virtual CD-ROM drive, make sure it reads our Mac OSX installer ISO, make sure the code reads our blank disk image, and set it so that the QEMU application attempts to boot from the ISO, not the blank hard disk image.First, change the flag for[cc lang=”Bash”]boot -c[/cc] to [cc lang=”Bash”]boot -d[/cc]Change the [cc lang=”Bash”]-drive file=~/Mac-disks/9.2.img,format=raw,media=disk[/cc] so that the path matches the file path of the blank .dmg disk image that you made. Make sure to change the file extension and not to put any extra spaces into the code.Now, add another drive path flag to the code BEFORE the disk image drive flag. It should read something like: [cc lang=”Bash”]-drive file=~/QEMU/Mac_OS_Puma.iso,format=raw,media=cdrom[/cc], only substituting in the correct file path and name for your ISO.All told, the file should now look like this – note how all the code following “./qemu-system-ppc” is all on one line, even though the text wrapping in TextEdit will probably make it look otherwise for you:[cc lang=”Bash”]#!/bin/bash
    cd “$(dirname “$0″)”./qemu-system-ppc -L pc-bios -boot d -M mac99 -m 256 -prom-env ‘auto-boot?=true’ -prom-env ‘boot-args=-v’ -prom-env ‘vga-ndrv?=true’ -drive file=~/QEMU/Mac_OS_Puma.iso,format=raw,media=cdrom -drive file=~/QEMU/MacOSPuma.dmg,format=raw,media=disk -netdev user,id=network0 -device sungem,netdev=network0[/cc]Save the “qemu.command” file.
  6. Now we need to make this .command file (which is basically just a tiny Bash script) executable so that your host operating system knows to run it like an application just by double-clicking. Open the Terminal app and run[cc lang=”Bash”] $ chmod +x /path/to/qemu.command [/cc]either typing out the full file path yourself, or just drag-and-dropping the qemu.command file into Terminal to get the full path automatically.
  7. Double-click on the “qemu.command” file. If all has been set up correctly, after a minute you should boot into the Mac OSX Puma installer.
  8. Your blank .dmg file should show up as an available destination disk on which to install OSX! Once the full installer has run (takes a few minutes), the software will eventually try to reboot the machine, which at this point will just take you back into the ISO installer. Mash Command+Q to quit out of QEMU.
  9. Go back to your “qemu.command” file in TextEdit. Swap the [cc lang=”Bash”]boot -d[/cc] flag BACK to [cc lang=”Bash”]boot -c[/cc], and delete the -drive flag for the ISO installer entirely, just leaving the .dmg file attached. Save the file. At this point, you should now be able to just double-click the “qemu.command” file and launch into OSX Puma, installed on your virtual hard drive!(it may take a minute! remember this is not going to be nearly as quick/smooth as loading on original hardware – and that you’ll have to go through a bunch of Apple’s “registration” nonsense)
  10. You can always attach more disk images to the emulated environment by re-creating “-drive” entries with “media=cdrom” and the file path to your ISO/CDR in the “qemu.command” file and saving/relaunching QEMU.

Live Capture Plus and QuickTime for Java

One of the particular challenges of video preservation is how to handle and preserve the content on digital tape formats from the latter days of magnetic A/V media: Digital Betacam, DVCam, DVCPro, etc. Caught in the nebulous time of transition between analog and digital signals (the medium itself, magnetic tape, is basically the same as previous videotape formats like VHS or Betacam – but the information stored on them was encoded digitally), these formats were particularly popular in production environments but there were plenty of prolific consumer-grade efforts as well (MiniDV, Digital8). In some ways, this makes transferring content easier than handling analog formats: there is no “digitization” involved, no philosophical-archival conundrum of how best to approximate an analog signal into a digital one. One simply needs to pull the digital content off the magnetic tape intact and get it to a modern storage medium (hard disk, solid-state, or maybe LTO, which yes I know is still magnetic tape but pay no attention to the man behind the curtain).

 https://twitter.com/dericed/status/981965351482249216?ref_src=twsrc%5Etfw&ref_url=https%3A%2F%2Ftweetdeck.twitter.com%2F

However, even if you still have the proper playback deck, and the right cables and adapters to hook up to a contemporary computer, there’s the issue of software – do you have a capture application that can communicate properly with the deck *and* pull the digital video stream off the tape as-is?

The last bit is getting especially tricky. As DV-encoded formats in particular lost popularity in broadcast/production environments, the number of applications that can import and capture DV video without transcoding (that is, changing the digital video stream in the process of capture), while staying compatible with contemporary, secure operating systems/environments, has dwindled. That’s created a real conundrum for a lot of archivists. Apple’s Final Cut Pro application, for instance, infamously dropped the ability to capture native DV when it “upgraded” from Final Cut Pro 7 to Final Cut X (you can hook up and capture tapes, but Final Cut X will automatically transcode the video to ProRes). Adobe Premiere will still capture DV and HDV codecs natively, but will re-package the stream into a .mov QuickTime wrapper (you can extract the raw DV back out, though, so this is still a solid option for many, though of course for just as many more an Adobe CC subscription is beyond their means).

One of the best options for DV capture is (was?) a Mac application called Live Capture Plus, made by Square Box Systems as part of its CatDV media suite. It has great options for error handling (e.g. trying to read a problem area of a tape multiple times automatically if there’s dropout), generating DV files based on clips or scenes or timecode rather than the whole tape, remote tape deck control over the FireWire/Thunderbolt connection, etc; a bunch of ingesting stuff that’s more appealing to an archivist than an application primarily for editing, like Adobe Premiere. It also talks to you, which is fun but also terrifying.

Failed to power up

However, Square Box removed Live Capture Plus from its product list some years back, and as far as I’m aware has refused all pleas to either open-source the legacy code or even continue to sell new licenses to those in the know.

Let’s say you *are* lucky enough to still have an old Live Capture Plus license on hand, however. The Live Capture Plus GUI is built on Java, but an older, legacy version of Java, so when you first try to run the app on a contemporary OS (~10.10 and up), you’ll first see this:

Luckily, for at least the moment, Apple still offers/maintains a download of this deprecated version of Java – just clicking on “More Info…” in that window will take you there, or you can search for “Java for OSX” to find the Apple Support page.

OK, so you’ve downloaded and installed the legacy Java for OSX. Yet this time, when you try again to run Live Capture Plus, you run into this fun error message instead:


All right. What’s going on here?

When I first encountered this error message, even though I didn’t know Java, this error message provided two clues: 1) “NoClassDefFoundError” – so Java *can’t find* some piece that it needs to run the application correctly; and 2) “quicktime”/”QTHandleRef” – so it specifically can’t find some piece that relates to QuickTime. That’s enough to go on a search engine deep dive, where I eventually found this page where researchers at the University of Wisconsin-Madison’s zoology/molecular biology lab apparently encountered and solved a similar issue with a piece of legacy software related to, near as I can figure from that site, taking images of tiny tiny worms. (I desperately want to get in touch and propose some sort of panel with these people about working with legacy software, but am not even sure what venue/conference would be appropriate)

The only way my ’90s-kid brain can understand what’s happening

So basically, recent versions of Mac OS have not included key files for a  plugin called “QuickTime for Java” – a deprecated software library that allowed applications built in/on Java (like Live Capture Plus) to provide multimedia functionality (playback, editing, capture) by piggybacking on the QuickTime application’s support for a pretty wide range of media formats and codecs (including DV). Is this fixable? If you can get those key files, yes!

For now, both the downloads and instructions for what to do with these three files are available on that Hardin Lab page, but I’m offering them here as well. The fix is pretty quick:

 

I would only note a couple things, which is that I’ve successfully installed on to macOS Sierra (10.12) without needing to mess with the System Integrity Protection settings by just installing for the local user (i.e. putting the files into ~/Library rather than /System/Library); and that if you want to do this via Finder rather than the command line, here is how to get to the “View Options” box to reveal the Library folder in Finder, as mentioned in Step 1 above (a useful step in general, really, if you’re up to digipres shenanigans):

Once these files are in place, Live Capture Plus should open correctly and be able to start communicating with any DV/FireWire-capable deck that you’ve got connected to your Mac – again, provided that you’ve got a registration code to enter at this point.

A final word of warning, however. Live Capture Plus comes from the era of 32-bit applications, and we’re now firmly in the era of 64-bit operating systems. Exactly what all that means is probably the subject of another post, but basically it’s just to say that legacy 32-bit apps weren’t made to take advantage of modern hardware, and may run slower on contemporary computers than they did on their original, legacy hardware. Not really an issue when you’re in video/digital preservation and your entire life is work-arounds, but recently Mac OS has taken to complaining about 32-bit apps:

Despite 32-bit apps providing, near as I can tell, no actual security or compatibility concerns for 64-bit OSes (32-bit apps just can’t take advantage of more than 4GB of RAM), this is a pretty heavy indication that Apple will likely cut off support for 32-bit apps entirely sometime in the not-so-so-distant future. And that will go for, not just Live Capture Plus, but other legacy apps capable of native DV transfer (Final Cut 7, the DVHSCap utility from the FireWire SDK, etc.)

So go get those DV tapes transferred!!!!

Getting Started with BagIt in 2018

Take two!

In December, I hastily wrote an update to an old post about BagIt, the Library of Congress’ open-source specification for hierarchical packaging of files to support safe data storage and transfer. The primary motivation for the update was some issues that the Video Preservation course I work with  encountered with my instructions for installing the bagit-python command-line tool, so I wanted to double-check my process there and make sure I was guiding readers correctly. I also figured that it had been a couple years and I could write about new implementations while I was at it. A cursory search turned up a BagIt-for-Ruby library, so I threw that in there, posted, *then* opened up a call for anything I’d missed.

Uhhhh –  I missed a lot.

It was at this point, as I sifted through the various scripts, apps, tools and libraries that create bags in some way that I realized I had lost the thread of what I was even trying to summarize or explain.

Every piece of software using the BagIt spec ever? That, happily, is a fool’s errand – the whole point of the spec is that it’s super easy and flexible to implement, no matter how short the script. So…there’s a lot of implementations.

Every programming language with an available port/module for creating bags according to the BagIt spec? Mildly interesting for hybrid archivist/developers, but probably of less practical use for preservation students, or the average user/creator just trying to take care of their own files, or archivists that are less programming-inclined. A Ruby module for BagIt is objectively cool and useful – for those working/writing apps and scripts in Ruby. Given that setting up a Ruby dev environment requires some other command-line setup that I didn’t even get into, someone’s likely not heading straight to that module right out of the gate.

“Using BagIt” was/is the wrong framework. Too broad, too undefined, and as Ed Summers pointed out, antithetical to the spirit in which a simple, open source specification is made in the first place: to allow anyone to use it, anywhere, however they can – not according to one of four or five methods proscribed in a blog post.

So I am rewriting this post from the mindset, not of “here’s all the forms and tools in which BagIt exists”, but rather, “ok, so I’m learning what a bag is and why’s it useful – how can I make one to get started?”

Because the contents of a specification are terrific and informative, but in my experience nothing reinforces understanding of a spec like a concrete example. And not only that, but one step further – *making* an example. Technical concepts without hands-on labwork or activities to solidify them get lost – and budding digital preservationists told to use the BagIt spec need somewhere to start.

So whether you’re just trying to securely back up your personal files to a cloud service, or trying to get a GLAM institution’s digital repository to be OAIS-compliant, validation and fixity starts at square one. Let me do that as well.

What’s a bag?

Just for refresher’s sake, I’m going to re-post here what I wrote back in 2016 – so that this post can stand alone as a primer:

One of the big challenges in digital archiving is file fixity – a fancy term for checking that the contents of a file have not been changed or altered (that the file has remained “fixed”). There’s all sorts of reasons to regularly verify file fixity, even if a file has done nothing but sit on a computer or server or external hard drive: to make sure that a file hasn’t corrupted over time, that its metadata (file name, technical specs, etc.) hasn’t been accidentally changed by software or an operating system, etc.

But one of the biggest threats to file fixity is when you move a file – from a computer to a hard drive, or over a server. Think of it kind of like putting something in the mail: there are a lot of points in the mailing process where a computer or USPS employee has to read the labeling and sort your mail into the proper bin or truck or plane so that it ends up getting to the correct destination. And there’s a LOT of opportunity for external forces to batter and jostle and otherwise get in your mail’s personal space. If you just slap a stamp on that beautiful glass vase you bought for your mother’s birthday and shove it in the mailbox, it’s not going to get to your mom in one piece.

So a “bag” is a kind of special digital container – a way of packaging files together to make sure what we get on the receiving end of a transfer is the same thing that started the journey (like putting that nice glass vase in a heavily padded box with “fragile” stamped all over it).

Sounds great! How do I make a bag?

At its core, all you need to make a bag out of a digital file or group of files is an editor capable of making plain text files (.txt) and an ability to generate MD5 checksums. An MD5 generator takes *any* string of digital information – including an entire file – and encodes it into a 128-bit fingerprint; that is, a 32-character string of seemingly “random” letters and numbers. Running an MD5 generator on the same file will always produce the same 32-character string. If the file changes in some way (even some change or edit invisible to the user), the MD5 string will change as well. So this process of generating and checking strings allows you to know whether a file is exactly the same on the receiving end of a transfer as it was at the beginning.

BagIt bags facilitate this process via a “tag manifest” – a text file including all the digital files contained in the bag (the “data” in question) and their corresponding MD5 checksums. Packaged together (along with some meta information on the BagIt spec and the bag itself), this all allows for convenient fixity checking.

Convenient, though, in the sense of easing automation. While you *can* put together a bag by hand – generating checksums for each file, copying them into text files to create the manifests, structuring the data and manifests together in BagIt’s dictated hierarchy -that is a copy/paste nightmare, and not exactly going to encourage the computer-shy into healthier digipres practice.

This is why simple scripts and tools and apps are handy. Down the line, when you’re creating your own archival workflow, you may want to find or tweak or make your own process for creating bags – but for your first bag, there’s no need to reinvent the wheel.

I’m going to cover intro tools here, for either the command line or GUI user.

Command Line Tools

  1. this Bash scriptA simple shell script by Ed that just requires just two arguments: the directory you want to bag, and an output directory (in which to put the bag).Hit the green “Download” button in the corner of the GitHub page, select the ZIP file, then unzip the result. Move the “bagit.sh” file inside to a convenient/accessible location in your computer.Once in Terminal, you can run this bash script by navigating to wherever you put this script, then executing it with:[cc lang=”Bash”]$ ./bagit.sh /path/to/directory /path/to/bag[/cc]
    or
    [cc lang=”Bash”]$ bash bagit.sh /path/to/directory /path/to/bag[/cc]

    (the “./” or “bash” commands do the same thing – indicating to the Bash terminal to execute the bagit.sh script)

    The “/path/to/directory” should be a folder containing all the files you want to be in the bag. Then you will specify the output path for the bag with “/path/to/bag”. Both can be accomplished with drag-and-dropping folders from the Finder.

  2. bagit-pythonBagit-python is the Library of Congress’s officially-supported command line utility for making and working with bags. It requires a working Python interpreter on your computer, plus Python’s package manager, “pip”. By default, macOS comes with a Python interpreter (2.7.10), but not pip. So we go to the popular command-line Mac package manager Homebrew to put this all together.Sigh. OK. So one of the reasons this post didn’t come out last week is that, literally in that same time frame, Homebrew went through….something with regards to their Python packages and how they behaved with Python 2.x vs Python 3.x vs the Python installation that comes with your Mac. (they’ve locked/deleted a lot of the conversations and issues now, but it was really the dark side of FOSS projects in there for a bit). I kept trying to check my instructions were correct, and meanwhile, every “$ brew update” was sending my python installs haywire. It seems like they’ve finally settled, but, I’d still now generally recommend giving this page a once-over before working with python-via-homebrew.

But to summarize: if you want to work with Python 3.x, you install a *package* called “python” and then invoke it with python3 and pip3 commands. If you want to use Python 2.x, you install a package called “python@2” and then invoke with either python and pip or python2 and pip2 commands.

…got it?

For the purposes of just using the bagit-python command-line tool, at least, it doesn’t matter whether you choose Python 2.x or 3.x. It’ll work with both. But stick with one or the other through this installation process. So either:

[cc lang=”Bash”]$ brew install python[/cc]
+
[cc lang=”Bash”]$ sudo pip3 install bagit[/cc]

or:
[cc lang=”Bash”]$ brew install python@2[/cc]
+
[cc lang=”Bash”]$ sudo pip install bagit[/cc]

That’s it! It’s just making sure you have a version of python installed through Homebrew, then use the python package/module installer “pip”to install the bagit-python tool. I highly recommend using admin privileges with “sudo” to globally install and avoid some weird permissions issues that may arise from trying to run python scripts and tools like bagit-python otherwise.

One installed, look over the help page with [cc lang=”Bash”]$ bagit.py –help[/cc] to see the command syntax – and all the features that you can cover! Including using different hash generators (rather than MD5), adding metadata, validating existing bags rather than creating new ones, etc.

*** a note about bagit-java***
If you are using Homebrew and just run [cc lang=”Bash”]$ brew install bagit[/cc] it will install the bagit-java 4.12.3 library and command-line tool. The LOC no longer supports and doesn’t recommend this tool for command line use, and the –help instructions that come with it don’t even actually reflect the command syntax you have to use to make it work. So! This isn’t a recommendation but just a note for Homebrew users who might get confused about what’s happening here.

GUIs

1. Bagger

Again, the LOC’s official graphical utility program for creating and validating bags. Following the instructions from their GitHub repository linked above, you’re going to download a release and then run on macOS by finding and clicking on the “bagger.jar” file (you’ll need a working Java install as well).Inside Bagger, once you choose the “Create a Bag” option, Bagger will ask you to choose a “profile” – these just refer to the metadata fields available for inserting more administrative information about your bag and the files therein, within the bag itself. These are really useful for keeping metadata consistent if you’re creating a whole bunch of bags, but choosing “<no profile>” is also totally acceptable to get started (you can always re-open bags and insert more metadata later!)”Create Bag in Place” is also a useful option if you don’t want (or digital storage limitations even *prevents*) to have two copies of your files (the original + the copy inside the “data” folder in your bag). Rather than copying and creating the bag in a new directory elsewhere, it’ll just move around/checksum/restructure the files according to the BagIt spec within the original directory.

2. Exactly

A GUI developed by AVP and the University of Kentucky that combines the bagging process with file transfer – which is the presumed end-goal of bagging in any case. To that end, Exactly doesn’t “bag in place” – you always have to pick a source file/directory (or sources – Exactly will bundle them all together into one bag) and a destination for the resulting, created bag. Like Bagger, you can also add metadata via custom-designed fields or import templates/profiles. Added support for FTP or SFTP transfers to remote servers (in addition to locally-attached network storage units like a Samba or Windows share) make it a simple starter option for file delivery.

***************************

If you’re getting started with the BagIt spec, these are the places I’d begin. But as to what implementation *you* can come up with from there, based on your personal/institutional needs…that’s up to you!