Emaculation.com

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
basiliskii_osx_setup [2016/03/29 04:39] – [Preparing Your BasiliskII Folder] ronald_p._regensburgbasiliskii_osx_setup [2024/03/01 12:44] (current) – [Setting up System 7.5.3 with BasiliskII for OSX/macOS] ronald_p._regensburg
Line 1: Line 1:
-===== Setting up system 7.5.3 with BasiliskII for Mac OSX =====+===== Setting up System 7.5.3 with BasiliskII for OSX/macOS =====
  
-(Last updated June 17, 2013)+(Last updated March 1, 2024)
  
-(you can also set up [[Basilisk II  setup|Basilisk II for Windows]])+(You can also set up [[Basilisk II  setup|Basilisk II for Windows]] or [[sheepshaver basiliskii linux|Basilisk II for Linux]].)
  
 ==== Introduction ==== ==== Introduction ====
Line 9: Line 9:
 Basilisk II emulates up to a 68040 Macintosh, which can run Mac OS 7.x through 8.1. Basilisk II emulates up to a 68040 Macintosh, which can run Mac OS 7.x through 8.1.
  
-This manual can be used with [[http://www.emaculation.com/forum/viewtopic.php?f=6&t=7361|04-10-2009 or later builds]] of BasiliskII.+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: Please note:
  
-  * This manual describes setting up BasiliskII with MacOS 7.5.3 (free to download from Apple), inside a folder called BasiliskII in your Home folder. +  * 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 started from the BasiliskIIGUI. With only a restart in the emulated machine new settings will not be used. +  * 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.   * 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.+  * 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.   * 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.
  
Line 22: Line 23:
 ====Preparing Your BasiliskII Folder==== ====Preparing Your BasiliskII Folder====
  
-To start, you need to have some files in 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 [[https://www.emaculation.com/forum/viewtopic.php?f=6&t=7361|this forum post]]. 
 + 
 +  - The **BasiliskII application**, the actual emulator.\\ 
 +  - 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. 
 +  - A **floppy disk image** to boot the Mac. Best use the DiskTools_MacOS80.image. [[https://surfdrive.surf.nl/files/index.php/s/uQgbLJvgazBPN8s/download|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. 
 +  - **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. [[https://emaculation.com/basilisk/OS753InstallerParts.zip|Download it here.]] Unzip the file and move the OS753InstallerParts.dsk file into the BasiliskII folder. 
 +  - 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. 
 +  - 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. 
  
-  - The **BasiliskII application**, the actual emulator.\\ (**Retina screen:** If your Mac has a Retina screen, make sure that BasiliskII will run in low resolution mode. In the Finder: Select the BasiliskII icon, choose Get Info from the File menu, and place a checkmark next to "Open in Low Resolution".) 
-  - The **BasiliskIIGUI application**, to be used for setting up and configuring BasiliskII. 
-  - A **floppy disk image** to boot the Mac.  Download it [[http://www.open.ou.nl/hsp/downloads/DiskTools_MacOS80.image.zip|here]].  Unzip the file, and lock it. Select "Get Info" and check the “Locked” box. **Use only this floppy image**. System 7/7.5 floppy images will make you run into problems later during the installation process, because they don't allow the shared folder to appear on the desktop, see below.  
-  - 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. 
-  - A **keycodes file**.  The keycodes file is not necessary if you are using a US English QWERTY keyboard layout. 
-  - A **folder shared between OSX and BasiliskII**.  From within BasiliskII you will have access to a folder on the Mac OS X 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. **However**, this manual assumes that a shared folder in the BasiliskII folder called “Shared” is available.  Prepare for installation of MacOS by creating the Shared folder in your BasiliskII folder.  Then download the [[http://www.emaculation.com/basilisk/os753/|19 installer parts for System 7.5.3]] from Apple and place them in the folder. \\ Take a look at the file names. If the first is named with a ”.smi” extension and the others with a ”.part” extension, you can skip the next step of double-clicking all files individually. Double-clicking the files will unpack them, leaving you with the double amount of files in the folder. When finished, remove the files not named with the ".smi" or ".part" extensions.  
 ====Running BasiliskIIGUI==== ====Running BasiliskIIGUI====
-When the files needed are in the Basilisk II folder and when you have created a shared folder, you can start configuring Basilisk II: +**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** **1. Start BasiliskIIGUI**
  
-**2. Configure preferences in Volumes tab**+**2. Configure preferences in 'Volumes' tab**
  
-BasiliskII will always try to start from the first entry in this list. As we will start from a floppy disk, you’ll need to add the floppy disk image you downloaded to the list of Volumes (floppy or hard disk image files BasiliskII can use as disks).+**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 select the floppy disk image in your BasiliskII folder.  Note that the navigation might be a bit awkward for OSX users. (Following our example, in the left browser pane, browse to "Users", "your user name", "BasiliskII" and select the floppy disk image in the right browser pane)\\ +- Click “Add” and in the Open dialog select and "Open" the DiskTools_MacOS80.image file in your BasiliskII folder.
--Click OK\\+
  
-The floppy will show up in the volumes list.\\+The floppy volume will show up in the volumes list.
  
-{{:basosx_setup_disktools_1.png|}}+Next, we add the Installer disk image:
  
-Next, we’ll create a file that will be used as your Mac hard disk to install your future Mac OS on.+- Click “Add” and in the Open dialog select and "Open" the OS753InstallerParts.dsk file in your BasiliskII folder.
  
--Click “Create”\\ +The Installer volume will show up in the volumes list.
--Navigate to the folder you want to create the file in. \\ +
--Set the size for the hard disk. I would recommend 500 or 1000 Mb \\ +
--Give the file a name under "Selection", name it "MacOS753"\\ +
--Click OK\\ +
-(This can take some time, be patient)\\ +
-After the file is created, the window will close and you’ll see the preferences editor again. Notice the hard disk is also added to the list of volumes. For the installer parts to be available later on, we need to create another hard disk.\\ +
--Click “Create” to make a hard disk with size of 100Mb and name it “InstallerParts”.\\+
  
-{{:basosx_setup_3disks_2.png|}}\\+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:
 +
 +{{:basosx_setup_3disks_2.png}}
 +
 +**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". 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".
  
--Type the path to the shared folder in the field after "Unix Root". The line below shows what to enter when the folder is called Shared and is located in the BasiliskII folder in your Home folder.\\ +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/”hsp”/BasiliskII/Shared (replace my username with yours, and don’t use quotes!)\\+
  
-Now click the tab Graphics/Sound on the Preferences editor\\+**/Users/username/Desktop/Shared** (replace "username" with your short username!)
  
-**3. Configure preferences in Graphics/Sound tab**\\+Now click the tab Graphics/Sound on the Preferences editor
  
-{{:basosx_setup_graph_sound_3.png|}}\\+**3. Configure preferences in 'Graphics/Sound' tab**
  
--For now, leave the Video Type selection at "Window" (After installation you might select "Full Screen").\\ +{{:basosx_setup_graph_sound_3.png}}
--Select the desired screen refresh rate. On a fast, current machine, select "Dynamic". On a PowerPC machine, select e.g. 30Hz. (Higher rates slow the emulator down, 30Hz may improve performance and will lower the extreme CPU hunger of BasiliskII on PowerPC machines.) \\+
  
--Select the desired width and height of the emulator window. \\ +**Video Type**\\ 
-Set Width and Height for the window to 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. \\ +For now, leave the Video Type selection at "Window".\\ 
-The Audio Settings can be ignored. \\+(After installation you can select "Full Screen" if you want BasiliskII to start up in full-screen mode.)
  
-Move to the keyboard/Mouse tab\\+**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.)
  
-**4. Configure preferences in Keyboard/Mouse tab**\\+**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.
  
-{{:basosx_setup_key_mouse_4.png|}}\\+The Audio Settings can be ignored.
  
--Check “Use Raw Keycodes” and browse for the keycodes file in the BasiliskII folder if your keyboard lay-out is not US-English. \\ +Move to the keyboard/Mouse tab
-“Mouse Wheel Function” and “Lines to Scroll” are a matter of taste. The image shows the standard settings. \\+
  
-Move to the Serial/Network tab+**4. Configure preferences in 'Keyboard/Mouse' tab**
  
-**5. Configure preferences in Serial/Network tab**\\+{{:basosx_setup_key_mouse_4.png}}
  
-{{:basosx_setup_ser_net_5.png|}}\\+**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.
  
-In order to be able to use the internet in Basilisk, you need to set the Ethernet Interface to “slirp."+**Mouse Wheel Function** and **Lines to Scroll** are a matter of taste. The image shows the standard settings.
  
--Open the list box, select "slirp"\\ +Move to the Serial/Network tab (in the 64-bit beta Basilisk II GUI: Ports tab)
-Ignore the “Modem Port Device” and “Printer Port Device” settings.\\+
  
-Now move to the memory/misc tab\\+**5. Configure preferences in 'Serial/Network' or 'Ports' tab**
  
-**6. Configure preferences in Memory/Misc tab**\\+{{:basosx_setup_ser_net_5.png}}
  
-{{:basosx_setup_mem_misc_6.png|}}\\+**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.
  
-Several important choices are to be made here.+Other settings in this tab can be ignored.
  
--Set the amount of memory available to Mac OS in Basilisk. \\ +Now move to the Memory/Misc tab (in the 64-bit beta Basilisk II GUI: System tab)
--Set Mac Model ID to "Quadra 900" and CPU type to "68040" \\ +
--Select the rom file to be used. Click “Browse” and navigate to your rom file. Select it and click OK.\\ +
-Also set:\\ +
--"Don’t use CPU when idle" and "Ignore Illegal Memory Accesses" (this allows some badly written programs to run)\\+
  
-Next, click the JIT Compiler tab.\\+**6. Configure preferences in 'Memory/Misc' or 'System' tab**
  
-**7. Configure preferences in JIT Compiler tab**\\+{{:basosx_setup_mem_misc_6.png}}
  
-Please set the preferences as shown in the image below:\\ +Correct settings here are important. If configured incorrectly, setup may fail or BasiliskII may crash.
-{{:basosx_setup_jitcomp_7.png|}}\\+
  
 +**MaOS RAM Size (MB)**\\
 +The amount of memory available to Mac OS in Basilisk. Set it to **128** or **256**.
  
-**8. Click start!**\\+**Mac Model ID**\\ 
 +Set the Model ID to "Quadra 900".
  
--Click “Start” to save the settings and to start BasiliskII. \\+**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.
  
-==== Inside Mac OS ====+**Don't use CPU when idle** and **Ignore Illegal Memory Accesses**\\ 
 +Make sure both options are checked.
  
-During startup, the system will encounter the floppy and give a warning about running of a floppy disk.\\ +Next, click the JIT Compiler tab (in the 64-bit beta Basilisk II GUI: JIT tab)
  
--Click "OK" to proceed.+**7. Configure preferences in 'JIT Compiler' or 'JIT' tab**
  
-The system will now find the hard disks we created earlier (saying this is not a mac disk) and will offer to initialize them.\\ +{{:basosx_setup_jitcomp_7.png}}
  
--Give the first disk an appropriate name (for instance MacOS753) and choose Mac OS Standard as format.\\  +**Do not enable JIT compiler now!**\\ 
-{{:basosx_second_disk_initialize_9.png|}}\\+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. 
  
--Click "Initialize" to proceed with initializing the hard disk.\\  +**8. Click start!**
-{{:basosx_initialize_confirm_10.png|}}\\+
  
--Name the second hard disk “Installer Parts”. Again, click "Initialize" to proceed with initializing the hard disk.\\ +Click “Start” to save the settings and to start BasiliskII.
-{{:basosx_third_disk_initialize_11.png|}}\\+
  
-Finally, you will see the desktop with icons for: \\ +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.
--the startup volume (the disk tools floppy disk), \\ +
--the icon for the new hard disk that you will install the system onto (MacOS753),\\  +
--the icon of the disk that will hold your installer parts (Installer Parts) and \\ +
--the icon for the “Unix” volume that gives access to the shared folder on the Mac OS X side.\\ +
  
--Open the “Unix” hard disk and copy all 19 files onto the “Installer Parts” disk\\ 
-{{:basosx_Unix_disk_12.png|}}\\ 
--Copy all 19 files to the Installer Parts disk\\ 
  
-{{:basosx_Installer_Parts_13.png|}}\\+====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": 
 + 
 +{{:basosx_second_disk_initialize_9.png|}} 
 + 
 +- Click "Continue" to proceed with initializing the disk: 
 + 
 +{{:basosx_initialize_confirm_10.png|}} 
 + 
 +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. 
 + 
 +{{:basosx_Installer_Parts_13.png|}} 
 + 
 +- In the opened window, double-click the first part called “System 7.5.3 01of19.smi”. A floppy icon will appear on your desktop:
  
--On the "Installer Parts" disk, start the installation of Mac OS 7.5 by double-clicking the first part called “System 7.5.3 01of19.smi”. A CD image icon will appear on your desktop. \\ 
 {{:basosx_Sys75Inst_icon_14.png|}}\\ {{:basosx_Sys75Inst_icon_14.png|}}\\
  
--Double-click it and start the installer contained in the folder that opens. \\+- Double-click that icon to open the floppy image and start the installer contained in the window that opens.
  
-Proceed with the system installation and when the installation is completed, you can quit the installer. \\+- Choose "MacOS753" to install the system onto and proceed with the system installation.
  
--Quit Mac OS.\\+- When the installation has completed, you can quit the installer.
  
-Sometimes the BasiliskIIGUI needs a little kick, so if it is still running, Force Quit it.\\+- Shut Down Mac OS from the Finder Special menu, or quit BasiliskII and choose Shut Down from the dialog.
  
-==== Finishing ====+(If somehow the GUI application is still running, make sure to quit it now.) 
 +====Finally==== 
 + 
 +- Start BasiliskIIGUI again.
  
--Start the BasiliskIIGUI again. \\ 
 {{:basosx_setup_removedisks_16.png|}}\\ {{:basosx_setup_removedisks_16.png|}}\\
  
--On the volumes tab remove the "DiskTools_MacOS89.image" and "installerparts" disks.\\ +- From the volumes list, remove the "DiskTools_MacOS80.image" and "OS753InstallerParts.dsk" disks.
--On the memory/misc tab set the mac model id to support system 7.x\\+
  
--Click Start. \\+- 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!
  
-E voila!\\ 
 {{:basosx_running_os753_18.png|}} {{:basosx_running_os753_18.png|}}
  
-==== Support ====+====Good to know====
  
-Direct questions to our [[http://www.emaculation.com/forum|support forum]].  Note that this guide is partially derived from our SheepShaver for OS X setup guide.+**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: [[sheepshaver_basilisk_printing|Printing from SheepShaver and BasiliskII]]
 +
 +**AppleTalk**\\
 +See this guide: [[appletalk for sheepshaver|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 [[https://www.emaculation.com/forum|support forum]].