Sheepshaver preferences on OSX and Unix - sentient06/Medusa GitHub Wiki
I am still organising this content. Most of the options work just like Basilisk's. Be patient.
There is no official documentation on the SheepShaver Preferences file format and the existing information is not satisfactory. I'll copy here the information I got from SheepShaver's source code and cross-reference with Basilisk II's counterparts when applicable. With time, I hope to slowly complete this list to have a convenient reference on this matter.
SheepShaver is configured via the preferences file, which is a text file usually stored in the home directory of the user as so: ~/.sheepshaver_prefs.
If no preferences file is present, SheepShaver will create one with the default settings upon startup.
The preferences file can be nested in a ".sheepvm" bundle (folder with extension) and passed as an argument to the SheepShaver binary if it was compiled in or after 2012.
The preferences file is a text file editable with any text editor. Each line in this file has the format "keyword value" and describes one preferences item. For each keyword, the meaning of the "value" string may vary across platforms. The following keywords exist:
Usage:
ignoreillegal <"true" or "false">
Ignores illegal instructions. Default value is "false".
Usage:
rom <ROM file path>
This item specifies the file name of the Mac ROM file to be used by SheepShaver. If no "rom" line is given, the ROM file has to be named "Mac OS ROM" and put in the same directory as the SheepShaver executable.
Usage:
ramsize <bytes>
Allocate "bytes" bytes of RAM for MacOS system and application memory.
The value given will be rounded down to the nearest multiple of 1MB.
If you are using a Mac Classic ROM, the maximum available value is 4MB and higher values will be ignored. The default is 16MB.
Tests suggest there is a limit of 1GB (1024MB).
(Platform-specific)
Usage:
ignoresegv <"true" or "false">
Set this to "true" to ignore illegal memory accesses. The default is "false". This feature is only implemented on the following platforms: Linux/x86, Linux/ppc, Darwin/ppc.
Usage:
disk <volume description>
This item describes one MacOS volume to be mounted by SheepShaver. There can be multiple "disk" lines in the preferences file. SheepShaver can handle hardfiles (byte-per-byte images of HFS volumes in a file on the host system), HFS partitions on hard disks etc., and MacOS-partitioned disks (it can only access the first partition, though). The "volume description" is either the pathname of a hardfile or a platform-dependant description of an HFS partition or drive.
If the volume description is prefixed by an asterisk ("*"), the volume is write protected for MacOS.
SheepShaver can also handle some types of Mac "disk image" files directly, as long as they are uncompressed and unencoded.
To specify an HFS partition, simply specify its path, i.e. /dev/sda5.
If you want to access a MacOS-partitioned hard disk or removable volume (Jaz, Zip etc.) and your operating system doesn't understand MacOS partition tables, you can specify the block device name (e.g. "/dev/sda") to access the first HFS partition on the device. Under Linux, if you don't specify any volumes, SheepShaver will search /etc/fstab for unmounted HFS partitions and use these.
Usage:
floppy <floppy drive description>
This item describes one floppy drive to be used by SheepShaver. There can be multiple "floppy" lines in the preferences file. If no "floppy" line is given, SheepShaver will try to automatically detect and use installed floppy drives. The format of the "floppy drive description" is the same as that of "disk" lines.
Usage:
cdrom <CD-ROM drive description>
This item describes one CD-ROM drive to be used by SheepShaver. There can be multiple "cdrom" lines in the preferences file. If no "cdrom" line is given, SheepShaver will try to automatically detect and use installed CD-ROM drives. The format of the "CD-ROM drive description" is the same as that of "disk" lines.
Usage:
bootdrive <drive number>
Specify MacOS drive number of boot volume. "0" (the default) means "boot from first bootable volume".
bootdriver <driver number>
Specify MacOS driver number of boot volume. "0" (the default) means "boot from first bootable volume". Use "-62" to boot from CD-ROM.
(Platform-specific)
Usage:
ether <ethernet card description>
This item describes the Ethernet card to be used for Ethernet networking by SheepShaver. If no "ether" line is given, Ethernet networking is disabled (although the Ethernet driver of SheepShaver will behave like a "dummy" Ethernet card in this case). The "ethernet card description" is a platform-dependant description of an ethernet card.
General note: To use TCP/IP from MacOS, you should assign a different IP address to the MacOS (entered into the MacOS TCP/IP (or MacTCP) control panel). Otherwise there will be confusion about which operating system will handle incoming packets.
In OSX, the value usually used for the ethernet setting is slirp.
The information ahead is not confirmed (imported from Basilisk II).
For Mountain Lion upwards, a driver called tap can be used to enable AppleTalk support with the value etherhelper/tap0/bridge0/en0.
Refer to http://www.emaculation.com/forum/viewtopic.php?f=6&t=8067 for more details.
(Platform-specific)
--etherconfig STRING
path of network config script [default=none]
Unknown
Usage:
extfs <direcory path>
This item specifies the root directory for the "Host Directory Tree" file system (the "Unix/BeOS/Amiga/..." icon on the Finder desktop). All objects contained in that directory are accessible by Mac applications.
This feature is only available when File System Manager V1.2 or later is installed on the Mac side. FSM 1.2 is built-in beginning with MacOS 7.6 and can be installed as a system extension (downloadable from Apple, look for the FSM SDK in the developer section) for earlier MacOS versions.
Usage:
scsi0 <SCSI target> ... scsi6 <SCSI target>
These items describe the SCSI target to be used for a given Mac SCSI ID by SheepShaver. SheepShaver emulates the old SCSI Manager and allows to assign a different SCSI target (they don't even have to be on the same SCSI bus) for each SCSI ID (0..6) as seen by the MacOS. "scsi0" describes the target for ID 0, "scsi1" the target for ID 1 etc. The format of the "SCSI target" is platform specific.
The "SCSI target" has to be the name of a device that complies to the Generic SCSI driver API. On a standard Linux installation, these devices are /dev/sg0, /dev/sg1 etc. Note that you must have appropriate access rights to these devices and that Generic SCSI support has to be compiled into the kernel.
The "SCSI target" has the format <id>/<lun> (i.e. "2/0").
Usage:
screen <video mode>
This item describes the type of video display to be used by default for SheepShaver. If you are using a Mac Classic ROM, the display is always 1-bit 512x342 and this item is ignored. The format of the "video mode" is platform specific.
The "video mode" is one of the following (applies for Unix):
win/<width>/<height> win/<width>/<height>/<bits per pixel>
Color display in an X11 window of the given size. There are several resolutions and color depths available. The set of color depths depends on the capabilities of the X11 server, the operating system, and Basilisk II compile-time options, but 1 bit and the default depth of the X11 screen should always be available.
(This part is the Basilisk II's reference. Must check code for SheepShaver.)
If Basilisk II was configured with "--enable-xf86-dga":
dga/<width>/<height>
Full-screen display using the XFree86 DGA extension. The color depth (8/15/24 bit) depends on the depth of the underlying X11 screen.
width and height specify the maximum width/height to use.
If both width and height are set to 0: dga/0/0 it results in a "complete screen mode".
The information ahead is not confirmed (imported from Basilisk II).
If Basilisk II was configured with "--enable-fbdev-dga":
dga/<frame buffer name>
Full-screen display using the frame buffer device /dev/fb. The color depth (8/15/24 bit) depends on the depth of the underlying X11 screen.
The frame buffer name is looked up in the "fbdevices" file (which path can be specified with the "fbdevicefile" prefs item) to determine certain characteristics of the device (doing a "ls -l /dev/fb" should tell you what your frame buffer name is).
Usage:
frameskip <frames to skip>
For refreshed graphics modes (usually window modes), this specifies how many frames to skip after drawing one frame. Higher values make the video display more responsive but require more processing power. The default is "8". Under Unix/X11, a value of "0" selects a "dynamic" update mode that cuts the display into rectangles and updates each rectangle individually, depending on display changes.
Usage:
windowmodes <"true" or "false">
Bitmap of allowed windowed video modes. Default value is "false".
Usage:
screenmodes <"true" or "false">
Bitmap of allowed fullscreen video modes. Default value is "false".
Usage:
gfxaccel <"true" or "false">
Turns on QuickDraw acceleration. Default value is "true".
Usage:
seriala <serial port description> serialb <serial port description>
The first item describes the serial port to be used as Port A (Modem Port) by SheepShaver and the second item describes the serial port to be used as Port B (Printer Port). If no "seriala" or "serialb" lines are given, SheepShaver will try to automatically detect and use installed serial ports. The "serial port description" is a platform-dependant description of a serial port.
In Unix:
Specify the device name of a serial port (e.g. "/dev/ttyS0") or a parallel "lp" port (e.g. "/dev/lp1"; this only works under Linux and FreeBSD). See below for more information about parallel ports.
Parallel ports: If you select a parallel port it will look like a serial port to MacOS but SheepShaver will only allow data output and ignore baud rate settings etc. You should be able to get some printers to work with this method (provided that you have the right printer driver, like "Power Print" (see http://www.gdt.com)).
Usage:
keyboardtype <keyboard-id>
Specifies the keyboard type that BasiliskII should report to the MacOS. The default is "5" which is a "Apple Extended Keyboard II (ISO)", but many other numbers are understood by most versions of the MacOS (e.g. 11 is a "Macintosh Plus Keyboard with keypad", 13 is a "Apple PowerBook Keyboard (ISO)" )
For additional information, consult the source (which has absolutely nothing about this)
consult these pages:
http://utopia.knoware.nl/users/eprebel/Macintosh/InternationalKeyboards/index.html http://utopia.knoware.nl/users/eprebel/Macintosh/Keyboards/
The codes in these pages are Apple's "Standard Resource Types". There are two "Reserved Resource Type Names":
- 'KCAP' is the "Physical layout of keyboard" (used by Key Caps DA)
- 'KCHR' is the "ASCII mapping" (software)
Basilisk's keyboard layout is the KCAP value.
(Platform-specific)
Usage:
keycodes <"true" or "false"> keycodefile <keycodes file path>
By default, the X11 event handler in SheepShaver uses KeySyms to translate keyboard event to Mac keycodes. While this method is very compatible and ought to work with all X servers, it only works well if your keyboard has a US layout. If you set "keycodes" to "true", SheepShaver will use raw keycodes instead of KeySyms. The keycode depends only on the physical location of a key on the keyboard and not on the selected keymap. Unfortunately it depends on the X server being used and possibly also on the type of keyboard attached. So SheepShaver needs a table to translate X keycodes to Mac keycodes.
This table is read by default from /usr/local/share/BasiliskII/keycodes unless you specify a different file with the "keycodefile" item. A sample keycode file is included with SheepShaver.
(Platform-specific)
Usage:
mousewheelmode <mode>
If you have a mouse with a wheel, this option specifies whether moving the wheel will be reported to the MacOS as "Page up/down" (mode 0) or "Cursor up/down" (mode 1) keys.
(Platform-specific)
Usage:
mousewheellines <number of lines>
If "mousewheelmode" is set to mode 1 (Cursor up/down), this option sets the number of key events sent to MacOS for each wheel movement (the number of lines to scroll).
(Platform-specific)
Usage:
dsp <device name> mixer <device name>
Under Linux and FreeBSD, this specifies the devices to be used for sound output and volume control, respectively. The defaults are /dev/dsp and /dev/mixer.
A Just-In-Time (JIT) translation engine is available for x86. This is aimed at translating 68040 instructions to native equivalent code sequences, thus providing faster emulation speeds.
Usage:
jit <"true" or "false">
Set this to "true" to enable the JIT compiler. Default value is "true" if the JIT compiler was compiled in.
Usage:
jit68k <"true" or "false">
TYPE_BOOLEAN, false
enable 68k DR emulator
(Platform-specific)
Usage:
idlewait <"true" or "false">
Sleeps when idle. Default value is "true".
Usage:
nosound <"true" or "false">
Set this to "true" to disable all sound output. This is useful if the sound takes too much CPU time on your machine or to get rid of warning messages if SheepShaver can't use your audio hardware.
Usage:
nocdrom <"true" or "false">
Set this to "true" to disable Basilisk's built-in CD-ROM driver. The only reason to do this is if you want to use a third-party CD-ROM driver that uses the SCSI Manager. The default is "false".
Usage:
nogui <"true" or "false">
Set this to "true" to disable the GUI preferences editor and GUI error alerts. All errors will then be reported to stdout. The default is "false".
Usage:
noclipconversion <"true" or "false">
Don't convert clipboard contents. Default value is "false".
Usage:
nonet <"true" or "false">
Don't use Ethernet. Default value is "false".
Boolean options are parsed as 'true|on|yes' or 'false|off|no'.