Emaculation.com

Setting up System 7.5.3 with BasiliskII for OSX/macOS

(Last updated March 1, 2024)

(You can also set up Basilisk II for Windows or Basilisk II for Linux.)

Introduction

Basilisk II emulates up to a 68040 Macintosh, which can run Mac OS 7.x through 8.1.

This manual was revised for use with our 4 May 2019 and later builds of Basilisk II.
Setup of most older versions and builds, both PPC and Intel, is similar.

Please note:

  • This manual describes setting up BasiliskII with MacOS 7.5.3 (used to be a free download from Apple), inside a folder called BasiliskII in your Home folder.
  • Changed settings in preferences will take effect after BasiliskII has been newly launched (or started from the BasiliskIIGUI). With only a restart in the emulated machine new settings will not be used.
  • Using most compatible ROM files it is also possible to run up to MacOS 8.1 in Basilisk II.
  • Not covered here, but when installing MacOS from a CD, only generic retail Mac OS install CDs can be used. A system install CD that was originally provided with a new Mac will only install on that specific model. Since OSX 10.8 (Mountain Lion) OSX/macOS does not allow physical CDs to be mounted in the emulator.
  • Not covered here, but a disk image of a retail Mac OS install CD can be used instead of the real CD. The disk image must be in a non-compressed format and the image file must be locked in the Finder to convince the installer that it is on the original read-only CD.

Preparing Your BasiliskII Folder

To start, you need to have some files in your BasiliskII folder:
Download links for BasiliskII, the GUI, and the keycodes file can be found in this forum post.

  1. The BasiliskII application, the actual emulator.
  2. The BasiliskIIGUI application (in macOS 10.14 Mojave or earlier) or the Basilisk II GUI application (in macOS 10.13 High Sierra and later), to be used for setting up and configuring BasiliskII.
  3. A floppy disk image to boot the Mac. Best use the DiskTools_MacOS80.image. Download it here. Unzip the file, and lock it after you moved it into the BasiliskII folder: Right-click (or control-click) on the file, select “Get Info”, and check the “Locked” box in the Info pane.
  4. A System instal disk image. In this guide we use the the System 7.5.3 multipart installer as it was once distributed by Apple as a free download. Download it here. Unzip the file and move the OS753InstallerParts.dsk file into the BasiliskII folder.
  5. A compatible ROM file. Basilisk II will not run without a compatible ROM file. If BasiliskII does not find a compatible ROM file, it will immediately quit on launch. It may be difficult to get ahold of a compatible ROM file as distributing bare ROM files violates Apple license agreements. ROM files from Quadra and Performa machines work best. Google “redundant robot sheepshaver” for downloads.
  6. A keycodes file. The keycodes file is not needed if you use an US English QWERTY keyboard layout.

Creating a shared folder

From within BasiliskII you will have access to a folder on the OSX/macOS side. That folder will appear on the BasiliskII desktop as a disk named “Unix”. Files copied or saved in BasiliskII to the “Unix” disk will appear in the shared folder on the Mac OS X side and files placed in the shared folder on the Mac OS X side will appear in the “Unix” disk in BasiliskII. Before you start configuring BasiliskII, create a folder that can serve as shared folder. The folder can be anywhere it is convenient for you and it can have any name you like. This manual assumes that that the shared folder is named “Shared” and is created on your desktop.

Running BasiliskIIGUI

Note: There are different GUI applications available. The 32-bit “BasiliskIIGUI” can be used up to macOS 10.14 (Mojave). The newer 64-bit “Basilisk II GUI” (still in beta) can be used in 10.12 (Sierra) and later. The example images here are from the 64-bit beta “Basilisk II GUI”, but the actual settings are similar in all GUI versions.

When all needed files are in the Basilisk II folder you can start configuring Basilisk II:

1. Start BasiliskIIGUI

2. Configure preferences in 'Volumes' tab

Volumes list
BasiliskII will always try to start up from the first entry in this list. We will start up from the floppy disk image you downloaded, so you will need to add that floppy disk image as the first disk to the list. (BasiliskII uses floppy or hard disk images as disks):

- Click “Add” and in the Open dialog select and “Open” the DiskTools_MacOS80.image file in your BasiliskII folder.

The floppy volume will show up in the volumes list.

Next, we add the Installer disk image:

- Click “Add” and in the Open dialog select and “Open” the OS753InstallerParts.dsk file in your BasiliskII folder.

The Installer volume will show up in the volumes list.

Finally, we will create a file that will be used as your Mac hard disk to install your future Mac OS on:

- Click “Create”
- Navigate to the folder you want to create the file in
- Give the file an appropriate name, like “MacOS753”
- Set the size for the hard disk. I would recommend 500 or 1000 Mb
- Click Save
(This can take some time, be patient.)

When the file is created, the window will close and you’ll see the preferences editor again. Notice that the hard disk is added to the list of volumes.

You should now see all three disk image files in the Volumes list:

Unix Root
In order to have the shared folder available to exchange files between OSX and Mac OS, we need to set the location of that folder at “Unix Root”.

Depending on the used GUI application, you can use the “Browse” button to find and add the Shared folder on your desktop to the field after “Unix Root” or you may need to type the path to the shared folder in that field. The line below shows what to enter when the folder is called Shared and is located on your desktop:

/Users/username/Desktop/Shared (replace “username” with your short username!)

Now click the tab Graphics/Sound on the Preferences editor

3. Configure preferences in 'Graphics/Sound' tab

Video Type
For now, leave the Video Type selection at “Window”.
(After installation you can select “Full Screen” if you want BasiliskII to start up in full-screen mode.)

Window Refresh Rate
Select “Dynamic” for the Window Refresh Rate.
(Only on older PowerPC machines, select a lower refresh rate, e.g. 30Hz. On such machines, 30Hz may improve performance and will lower the extreme CPU hunger of BasiliskII on PowerPC machines.)

Width and Height
Select the desired width and height of the emulator window.
Set lower values than the resolution of your actual screen. If you have a large screen, you can manually enter higher values than those in the menus, for instance 1280 x 800.

The Audio Settings can be ignored.

Move to the keyboard/Mouse tab

4. Configure preferences in 'Keyboard/Mouse' tab

Raw Keycodes
If your keyboard layout is not US English QWERTY:
Check “Use Raw Keycodes” and browse for the BasiliskII_keycodes file in the BasiliskII folder.

Mouse Wheel Function and Lines to Scroll are a matter of taste. The image shows the standard settings.

Move to the Serial/Network tab (in the 64-bit beta Basilisk II GUI: Ports tab)

5. Configure preferences in 'Serial/Network' or 'Ports' tab

Ethernet Interface
In order to be able to use the internet in BasiliskII, you need to set the Ethernet Interface (or Ethernet Port) to “slirp“:
Select “slirp” from the menu in the box.

Other settings in this tab can be ignored.

Now move to the Memory/Misc tab (in the 64-bit beta Basilisk II GUI: System tab)

6. Configure preferences in 'Memory/Misc' or 'System' tab

Correct settings here are important. If configured incorrectly, setup may fail or BasiliskII may crash.

MaOS RAM Size (MB)
The amount of memory available to Mac OS in Basilisk. Set it to 128 or 256.

Mac Model ID
Set the Model ID to “Quadra 900”.

CPU Type
Set CPU type to “68040”

ROM File
Select the rom file to be used. Click “Browse” and in the Open dialog navigate to the rom file you placed in the BasiliskII folder and Open it.
The path to the rom file should now appear in the text field.

Don't use CPU when idle and Ignore Illegal Memory Accesses
Make sure both options are checked.

Next, click the JIT Compiler tab (in the 64-bit beta Basilisk II GUI: JIT tab)

7. Configure preferences in 'JIT Compiler' or 'JIT' tab

Do not enable JIT compiler now!
The other JIT compiler preferences can be set as shown in the image above. You will then only need to check the “Enable JIT compiler” box when you want or need to enable JIT compiler later.
Note 1: BasiliskII will be less stable with JIT compiler enabled.
Note 2: JIT compiler is not functional anymore on Apple Silicon, JIT settings will be ignored.

8. Click start!

Click “Start” to save the settings and to start BasiliskII.

If BasiliskII does not start and/or the GUI does not quit, click Start or Save in the GUI to save the settings, quit the GUI application, and launch BasiliskII directly.

In Mac OS

During startup, the system will encounter the floppy and give a warning about running of a floppy disk.

- Click “OK” to proceed.

The system will then find the macOS753 disk we created earlier, will find the disk unreadable, and will offer to initialize it.

- Give the disk an appropriate name (we use here again “MacOS753”) and click “Initialize”:

- Click “Continue” to proceed with initializing the disk:

Finally, you will see the desktop with icons for the mounted volumes (disks):

  • Disk Tools 1, the startup volume on the DiskTools_MacOS80.image floppy disk image
  • OS753InstallerParts, that contains the 19 part System 7.5.3 installer
  • MacOS753, the newly created disk that you will install the system onto
  • Unix, the volume that gives access to the shared folder on the OSX/macOS side

- Open the OS753InstallerParts disk.

- In the opened window, double-click the first part called “System 7.5.3 01of19.smi”. A floppy icon will appear on your desktop:


- Double-click that icon to open the floppy image and start the installer contained in the window that opens.

- Choose “MacOS753” to install the system onto and proceed with the system installation.

- When the installation has completed, you can quit the installer.

- Shut Down Mac OS from the Finder Special menu, or quit BasiliskII and choose Shut Down from the dialog.

(If somehow the GUI application is still running, make sure to quit it now.)

Finally

- Start BasiliskIIGUI again.


- From the volumes list, remove the “DiskTools_MacOS80.image” and “OS753InstallerParts.dsk” disks.

- Click “Start” to save the changed settings and to start BasiliskII.
(Again, if BasiliskII does not start and/or the GUI does not quit, click Start or Save in the GUI to save the settings, quit the GUI application, and launch BasiliskII directly.)

Et voila!

Good to know

Better do not restart
Restarting may cause BasiliskII to freeze or crash. Instead, shut down and start again.

The Startup Disk control panel is not functional in BasiliskII
BasiliskII will startup from the first bootable volume in the Volumes list. Trying to use the Startup Disk control panel may cause BasiliskII to crash.

How to enable sound in BasiliskII
In “Sound” control panel, select “built-in” for the output device. In 8.1, the Sound control panel is sometimes installed in the “Apple Extras” folder. You can use it there to select the built-in output device.

How to enable network access
Set the TCP/IP control panel to Ethernet and DHCP. As soon as you start using IP network access, for instance with a web-browser, the IP addresses will become visible in the control panel.

Control-return window/fullscreen toggle
BasiliskII will launch in either window mode or full-screen mode according to the settings in the GUI application. Regardless, you can toggle between window mode and full-screen mode using Control-return.

Control-F5 grabbing mouse cursor toggle
Control-F5 will contain the mouse cursor within the BasiliskII window. This may be useful with some games.

Printing
See this guide: Printing from SheepShaver and BasiliskII

AppleTalk
See this guide: Appletalk for SheepShaver/Basilisk in Leopard, Snow Leopard or Lion (32 and 64 bit)

The shared folder / "Unix" disk

Transferring files
As explained above, the shared folder that you created in OSX/macOS will appear on the BasiliskII desktop as a disk (a volume) named “Unix”. Files copied or saved in BasiliskII to the “Unix” disk, will appear in the shared folder on the OSX/macOS side and files placed in the shared folder on the OSX/macOS side will appear in the “Unix” disk in BasiliskII. That way you can use the shared folder and the “Unix” disk to transfer or exchange files in both directions.

Applications cannot run properly from the “Unix” disk
If you use the shared folder and “Unix” disk to transfer applications for use in BasiliskII, always copy the applications and related files within BasiliskII from the “Unix” disk to the startup system volume (or to another mounted disk image volume) before actually using them.

Note that moving files directly from the “Unix” disk onto the BasiliskII desktop, does not copy them to the startup system volume. Those files will still be on the “Unix” disk, in fact inside the folder “Desktop Folder” in the shared folder.

Trashing files
Trashing files from the shared folder should be done at the OSX/macOS side. On the Mac OS side, the trash cannot be emptied when it contains files from the “Unix” disk.

Mounting additional volumes

Using the GUI application
In the GUI app you can create additional volumes (disk image files) or add existing compatible disk image files as additional volumes. The next time you start BasiliskII, all volumes in the volumes list will appear on the BasiliskII desktop. BasiliskII will startup from the first bootable volume in the list.

Most older Mac disk images in HFS format can be mounted in BasiliskII.

Dynamically mount and unmount additional volumes while BasiliskII is running
This feature is available in 10 August 2023 and later builds.

Dropping a disk image file from the host into the BasiliskII window will mount the volume as a read-only CD-ROM.

The mounted image can again be removed by dragging it onto the Trash icon (in MacOS 8 and later also from the Special menu or from the contextual menu).

Only one image file can be mounted at a time in this way.

Advanced features (SDL2 port builds only)

These features can be activated by manually editing the preferences file (the hidden ~/.basilisk_ii_prefs file).

• Changing the hotkey
By default, the hotkey used with window/full-screen toggle and mouse grabbing toggle is the Control key (Control-Return and Control-F5). You can change the hotkey by adding a “hotkey” item to the preferences file:

1: control(default)
2: option
3: control+option
4: command
5: control+command
6: option+command
7: control+option+command

For instance, you can set the hotkey to Control-Command by adding this line to the preferences file:

hotkey 5

• Offset date in years and/or days (20 February 2019 and later builds)
The date inside BasiliskII can be set in the past or in the future, in years and/or days. This may be needed for using some specific software. Adding these lines to the preferences file will set the date to 25 February 1989 when the actual date on the host is 20 February 2019:

yearofs -30
dayofs +5

Note: This feature can mix up relations between older files and newer files and between files' creation dates and modification dates. It should only be used by experienced users who know what they are doing.

• Changing scaling algorithm (Works as intended in 24 February 2019 and later builds)
Using nearest-neighbour or integer scaling will improve display quality when a low resolution emulator screen is displayed on a high resolution monitor (Retina screen). Nearest-neighbour or integer scaling can be applied by adding one or both of these lines to the preferences file:

scale_integer true
scale_nearest true

• Enlarging window size (22 September 2020 and later builds)
Enlarge BasiliskII window while preserving guest screen resolution. At next launch, the window will appear twice the set resolution when this line is added to the preferences file:

mag_rate 2

• Guest gamma ramp pass on to the host (22 September 2020 and later builds)
With this feature enabled, the guest gamma settings will be passed on to the host. This could improve color and brightness accuracy, but only when guest gamma settings and host screen properties match. The guest gamma settings will usually not match with modern screens. There are three possible settings:

gammaramp off
gammaramp on
gammaramp fullscreen

The default is “off”. When set to “fullscreen”, the feature works only in full-screen mode.

• Port forwarding in slirp networking
For instance:

redir tcp:8000:10.0.2.15:80

See this forum topic: https://www.emaculation.com/forum/viewtopic.php?f=6&t=7782

• Set custom window title (27 February 2021 and later builds)
By adding a prefs item title one can choose a different title for the BasiliskII window. For instance:

title BasiliskII System 7.5.3

• Shorten the sound buffer (17 March 2021 and later builds)
Shortening the length of the sound buffer can prevent delayed and choppy sound in some applications but will increase CPU use. The default setting is:

sound_buffer 0

Setting the value to 1 will halve the length of the sound buffer, setting the value to 2 will again halve the length, and so forth.

• Reverse scrolling (17 March 2021 and later builds)
The value for mousewheellines (“Lines to Scroll” in the GUI) can be set to a negative value, thus reversing the scroll direction. It needs to be entered manually in the prefs file as it cannot be set yet in the latest GUI app, but the GUI will respect the negative value when it saves other settings.

mousewheellines -1

• File name encoding in “Unix” (shared folder) (21 April 2021and later builds)
Classic MacOS files in the shared folder with non-MacRoman file names will show incorrect or garbled file names in the “Unix” volume in BasiliskII, even if the MacOS installed in BasiliskII uses the corresponding language and encoding. This may be corrected with an additional prefs item “name_encoding”:

1: Japanese
2: Chinese Traditional
3: Korean
4: Arabic
5: Hebrew
6: Greek
7: Cyrillic
25: Chinese Simplified

For instance, adding this line to the preferences file will correct Japanese characters:

name_encoding 1

When “name_encoding” is not specified, the default MacRoman will be used.
A full list of encodings can be found here: https://opensource.apple.com/source/CF/CF-550/CFStringEncodingExt.h.auto.html

• Slow down emulation (13 september 2022 and later builds)
Most software runs much faster in BasiliskII than on the original machines. For some speed dependant applications the emulation needs to be slowed down. This can be done with prefs item “delay”. The default setting is:

delay 0

If you need this feature, first try

delay 1000

and adjust the value as needed. The value is the additional delay in micro seconds for each 64k instruction.

• Startup with mouse cursor grabbed (28 February 2024 and later builds)
The mouse cursor grabbing feature (toggle with Control-F5, see above) is normally off by default. It will be on by default if this line is added to the prefs file:

init_grab true

Known issues

Crash at startup
On some host machines and/or with some configurations in the installed Mac OS system, BasiliskII will crash during Mac OS startup. In the crash log you will then typically find a line that ends with “SIGSEGV”.

Most of these crashes can be prevented by checking “Ignore Illegal Memory Accesses” in the 'Memory/Misc' or 'System' tab in the GUI app as advised in the configuration directions above.

CapsLock issue
If BasiliskII is launched while CapsLock is active, typed text will not correctly reflect the CapsLock status.

One press on the CapsLock key will correct the issue.

Support

Direct questions to our support forum.

basiliskii_osx_setup.txt · Last modified: 2024/03/01 12:44