This text file documents one user's learning experiences with DOSBox-X under Mac OS X 10.14 (Mojave). Primarily this involves discovering things that are not in the documentation (DOSBox-X Wiki, etc.) and/or that were not intuitively obvious to this user on first reading. Since this user's goal was to run certain DOS applications, there are no Windows-specific remarks here. In terms of hardware emulation, this document is only concerned with keyboard, mouse, monitor and virtual hard drives, because all printing is done from the Mac environment, operating only on plain text files. CONTEXT This document applies to the download named "dosbox-x-macosx-x86_64-10.13.zip"; when un-zipped, it yields a folder named "dosbox-x-macosx-x86_64-10.13" containing two Unix executables: dosbox-x-sdl1 and dosbox-x-sdl2. The Wiki states that SDL1 and SDL2 have somewhat different functionality, and gives one example, but does not fully explain the differences. This document was derived from experiences in using the SDL1 version. (Perhaps SDL refers to a Software Development Library.) Searching for SDL1 in the Issues section of github.com (https://github.com/joncampbell123/dosbox-x/issues) may reveal an old string of messages that explains the distinction somewhat. Although there is a new release of DOSBox-X every month, I have not found it necessary to obtain anything newer than that which was identified in the preceding paragraph, because my needs are simple. OPERATING CONCEPT There is no "install" process -- the downloaded executable is the DOS emulator, and it is self-configuring. (Maybe this is what the Wiki means by "portable"?) Additional configuration options are available after startup, and will be saved for use at the next startup, though where they are saved apparently depends on how the executable was started (see next section). Thus it is apparently possible to save multiple different configurations. All startup methods will initially open a 25x80 VGA terminal emulation window in which the DOS emulation appears. Some methods will also open a 24x80 Terminal window containing a log of various events involved in starting up and running the DOS emulation. STARTUP There are at least four different ways to start the DOSBox-X emulation process. A security restriction applies to at least one of these, and possibly to all of them. In the Security & Privacy panel of the Mac System Preferences, on the Privacy tab, there is an option that controls which downloaded apps can be executed without special permission. Those that do not come from either the App Store or an identified (approved) developer cannot be run without special permission. Since DOSBox-X does not fall into either category, attempting to execute it (by double-clicking = method #1 below) produces an error message "can’t be opened because it is from an unidentified developer." Unfortunately, the message box doesn't explain what to do about this. Solution: open System Preferences, Security & Privacy panel, Privacy tab, and you will find a one-time option to allow DOSBox-X to run. After choosing that option, the DOSBox-X executable will always run when double-clicked. It is not intuitively obvious whether this limitation on execution permission applies to the other methods of startup, since they were not tried until after the above problem had been solved. 1. Locate dosbox-x-sdl1 in a Finder window, then double-click it. Double-clicking the chosen version of DOSBox-X (either SDL1 or SDL2) opens a DOS emulation window and one or two Terminal windows, one containing a log of various events involved in starting up and running the DOS emulation. 2. Start from a Terminal window via the "open" command: open -a ~//dosbox-x-macosx-x86_64-10.13/dosbox-x-sdl1 starts the program with the DOS emulation window but without any additional Terminal windows. For CSZ: open -a ~/Documents/\ CARL/dosbox-x-macosx-x86_64-10.13/dosbox-x-sdl1 [Note backslash-space in front of CARL !] 3. Start from a Terminal window as a direct command: Entering this at the Terminal command line: ~//dosbox-x-macosx-x86_64-10.13/dosbox-x-sdl1 starts the program with the DOS emulation window, and uses the current Terminal window to log the startup events. For CSZ: ~/Documents/\ CARL/dosbox-x-macosx-x86_64-10.13/dosbox-x-sdl1 [Note backslash-space in front of CARL !] 4. Start from an Applescript In the Script Editor, entering this: activate application ":dosbox-x-macosx-x86_64-10.13:dosbox-x-sdl1" starts the program with the DOS emulation window but without any Terminal window, using the "private/var/folders/..." configuration file. From the Script Editor, this one-line script can be compiled and saved as an application. For CSZ: activate application "Macintosh HD:Users:carl:Documents: CARL:dosbox-x-macosx-x86_64-10.13:dosbox-x-sdl1" [Note space in front of CARL !] 5. Restart from the Apple menu "Recent Items" submenu: The Unix executable named "dosbox-x-sdl1" is NOT regarded as a "application" by Mac OS X, and thus does not appear in the Applications section of the Recent Items sub-menu in the Apple menu. Instead, it appears in the Documents section of that sub-menu. In order to execute it from there, the Finder must be foremost when the Apple menu is opened; otherwise, MacOS will pass the Unix executable as a document to be opened by the foremost open application, and that almost certainly will not work. If method 4 above was used to compile a script into an application named "DOSBox," then "DOSBox.app" appears in the Applications section of the Recent Items sub-menu, so that this becomes the easiest way to restart the emulator. For all 5 methods above: On startup (without any command-line options), the DOS emulation window displays some splash text too briefly to be read, then displays a blue box with a bit of introductory information, followed by some plain text which effectively pushes the top part of that blue box out the top of the window. Presumably, starting DOSBox-X from a Terminal command line would allow the use of the command-line options that are documented in the Wiki to suppress this blue box, which might then allow reading of the splash text; but I have not tried this yet. Alternatively, hitting the space bar as soon as the window starts to open will cause a pause that allows reading that startup text. (But it doesn't help in reading the first part of the blue box.) STARTUP OPTIONS The command line options documented in the Wiki can only be used when DOSBox-X is started from a Terminal command line (methods 2 & 3 above). Using "-noautoexec" does NOT bypass the Welcome page. Using "-fastlaunch" bypasses that as well as whatever preceding display exists, so there is NO obvious way to see what that preceding text is. (But see preceding section.) SHUTDOWN Closing the DOS emulation window terminates DOSBox-X, but does not close any associated Terminal window, nor does it terminate the Terminal app if that is running. If a DOS app is running, you will be required to confirm that you really do want to terminate DOSBox-X. CONFIGURATION FILES The Wiki says that the configuration file should be located in ~/Library/Preferences/DOSBox-X 0.83.14 Preferences and that is correct. But there is also a file "dosbox-x-sdl1.plist" in the same place, and elsewhere is a file named "~/dosbox-x.conf". Again, which one is used apparently depends on how the executable was started (see above); but I have not yet found which is which. The Wiki also says "there is a configuration file (dosbox-x.conf in the current directory or in your user directory)", and on a Mac system that is the root directory of the currently logged-in user. But that only happens if dosbox-x-sdl1 is started by double-clicking it. If dosbox-x-sdl1 is started by using the "activate" command in an Applescript, a dialog window opens with the heading "Select folder where to run emulation, which will become DOSBox-X's working directory." The folder name offered is "d", and it appears to contain only dosbox-x-sdl1, but its actual location is not obvious from the dialog. After selecting that folder, another dialog is presented, as follows: DOSBox-X working directory Do you want to use the selected folder as the DOSBox-X working directory in future sessions? If you select Yes, DOSBox-X will not prompt for a folder again. If you select No, DOSBox-X will always prompt for a folder when it runs. If you select Cancel, DOSBox-X will ask this question again next time. [ Cancel ] [ No ] [ Yes ] However, after selecting Yes, the "d" folder cannot be found via Finder. In the Configuration Tool, settings group Main, the item "working directory default" shows this: /private/var/folders/26/2tb563f1259482mxs5cnbm4h0000gp/T/AppTranslocation/5BC4CCEE-3412-410C-A930-A94C956B318E/d and the settings group AUTOEXEC.BAT shows blank, not the 1-line version of the original attempt. WINDOW CONFIGURATIONS There are two different methods of managing the configuration of the DOS emulation window, and they are mutually exclusive, i.e., changes to the configuration using one method have absolutely no effect on the configuration associated with the other method. The first method is the default, and is seen on initial startup; it uses a default mono-spaced display font that automatically resizes itself as the window size is changed; this is equivalent to a typical hardware display (monitor). The second method uses a user-specified True Type font (which acts monospaced even if it isn't), and the window size is determined largely by that font and its related parameters of line count and column count. Dragging the right edge or lower edge or lower right corner of the Terminal window changes the number of rows and/or columns displayed, which can be helpful in reducing the number of wrapped lines (and therefore improving readability). But I have not yet found any useful information here, so I suggest hiding this window if the chosen startup method (see above) opens it. Similar dragging on an edge or corner of the DOS emulation window in default mode does NOT change the number of rows and/or columns displayed, but instead changes the proportions of the displayed characters. Enlarging it in this way may improve readability. There are DOS commands that can change the number of rows (25,43,50,60) and columns (80,132); look in directory Z:\TEXTUTIL. These only work when the output is NOT in TTF mode. When the output is in TTF mode, the size of the DOS emulation window is determined by a combination of the chosen font with the Render configuration settings for ttf.lins (# of lines), ttf.cols (# of columns) and ttf.winperc (% of window); in this situation, dragging of the sides or corners is not possible. The ttf.winperc parameter applies to the vertical dimension of the (primary) screen, regardless of the horizontal dimension of that screen; the dimensions of any additional screen(s) are ignored, even if the emulation window is moved off the primary screen. DRIVE CONFIGURATIONS On startup, the DOS current (default) drive is Z:, which contains files CONFIG.SYS, AUTOEXEC.BAT and COMMAND.COM plus directories 4DOS, BIN, DOS, DEBUG, SYSTEM, TEXTUTIL. This Z drive and its contents are somehow hidden in the Mac filesystem. That's unfortunate, because it would be nice to be able to edit the AUTOEXEC.BAT file using a native Mac text editor instead of DOS EDIT, though that is also impossible for a different reason (see below). The customary drives A:,B:,C:, &c. are not initially defined, though all 25 letters of the alphabet other than Z are available for mounting various things as actual or emulated devices. The MOUNT command can be used to attach directories copied from a physical PC as virtual drives. Drives A,C,D can also be used to boot from a drive or a disk image (not tested by this author). Documentation says: "DOSBox-X allows you to freely customize the internal virtual drive Z: in the configuration, including adding your own files to the Z drive, or hiding/replacing existing files on the Z drive, with directory support." BUT: The only possibility I can find is editing AUTOEXEC.BAT and CONFIG.SYS via the Configuration tool. ANSWER: Look in the FAQ. KEYBOARD Most of the Special Keys listed on the Wiki Welcome page do not work with a Mac keyboard, because function keys cannot be combined with other keys. While Mac keyboards do have function keys, they are normally assigned to control hardware functions (e.g, screen brightness, keyboard illumination, sound output volume). The "fn" combining key (similar to Shift, Control and Option) is used to force them to act instead as software function keys (which is the way PC function keys always work); this option can be reversed using System Preferences > Keyboard. This problem can be avoided by attaching a PC keyboard, preferably via a USB connection like the Mac keyboard. With two keyboards attached, Mac OS X accepts inputs from both interchangeably; and when the DOS emulation window has focus, it reacts to inputs from the PC keyboard as expected. The Mapper Editor described on the Wiki Welcome page has an additional function that is not documented there -- press any key on the keyboard and the corresponding part of the diagram reverses color (from white on black to black on white) as long as the key is held down, and the bottom line of the Mapper window shows the corresponding numeric codes and key name. The Mapper Editor does not recognize the Mac "fn" combining key at all, and F11 (fn+F11) is intercepted by Mac OS X Mission Control (though that can be turned off in System Preferences > Keyboard); this is another reason for using an auxiliary PC keyboard. DATE & TIME When DOSBox-X is started, it syncs its date & time with the host system. However, when it is idle, its internal clock does not get updated unless "Synchronize host date/time" is checked in the DOS menu of the emulator. This option can be specified in the Main section of the configuration tool, as well as in the [dosbox] section of the configuration file. Since this can be important for maintaining accurate timestamps in the host filesystem, I don't know why it isn't specified by default. DOS EDIT The DOS command EDIT is available, but has one quirk that can cause trouble. The default drive for a file specified on the EDIT command line is the current drive (initially Z), but the default drive for saving that file after making changes is somewhere else. The Save As dialog seems to indicate that EDIT expects the A drive to be available, even when it isn't. Furthermore, it is impossible to Save As to the Z drive; an error message may or may not appear, and apparently the Z drive is read-only. So the file Z:AUTOEXEC.BAT cannot be modified this way, either. AUTOEXEC.BAT To change the contents of this file, it is necessary to use the DOSBox-X Configuration Tool, which is the first entry in the Main menu on the Mac menubar. Alternatively, the "conf" file can be edited directly; its "autoexec" section is at the very end of the file. MOUSE Although the documentation says that the emulated PC includes operation of a mouse, I have not found that to be very workable. There is a "capture mouse" function which can be turned on either from the emulator's Main menu or by the Ctrl+F10 keystroke; once captured, it can only be un-captured by using the Ctrl+F10 keystroke. (Oddly, this "capture" function is not on the emulator's Capture menu.) When not captured, the usual Mac cursor can be moved over the DOSBox-X window, though it may or may not be visible, depending on what DOS application is running. And if it is visible, clicking the mouse may not have the expected effect on the DOS program that is running. In my experience with one program, that seems to work like pressing the Enter key for whatever had previously been selected by using arrow keys. That is, any motion of the mouse is ignored. When captured, the mouse is confined to the DOSBox-X window, though without any visible cursor. Of the two DOS programs I use that are known to respond to a mouse, one works properly (moving the selection highlight from field to field, either L-R or up-down) but the other does not (an expected highlight of a character does not happen). Unfortunately for me, that is the program where a mouse would potentially be useful (though it is not essential). The scroll wheel works whether the mouse is captured or not, and its operation (a translation to a configurable pair of keystrokes) is controlled by a submenu of the emulator's Main menu. CLIPBOARD It is possible to paste text from the Mac clipboard into an emulated DOS application using Ctrl+F6. (This is documented in the Wiki.) Fortunately, this key combination is not defined for some other purpose in Kedit, which is where I will find it extremely useful. OUTSIDE THE WINDOWS When the DOS emulation window has focus, the standard Mac menubar at the top of the screen offers ten menus that contain a wide variety of controls for the emulated DOS system and emulated hardware. This user made no attempt to explore all those controls, so only a few of them may be mentioned in the following paragraphs (or have been mentioned above). But all appear to be documented in the Wiki, though I have not exercised them to verify the adequacy of that documentation. The program menu in the Mac menubar does not offer the expected Preferences... option. Instead, one must use the Configuration Tool in the Main menu. The program menu item "About dosbox-x-sdl1" is useless, because it only echoes the program name; it does not present the version number. The program menu item "Hide dosbox-x-sdl1" sometimes does not work, and neither does Command-H; other times they do, and it is not yet clear what makes the difference. The red/yellow/green buttons at the upper left corner of the DOSBox-X window do work more or less as expected in the Mac environment. The red button not only closes the window but also terminates DOSBox-X. The yellow button minimizes the window into the Dock. The green button maximizes the window into full-screen mode; however, the usual Mac method of exiting from full-screen mode (the Escape key) does not work. One method is to exit any DOS app that may be running and type "exit" at the DOS prompt; this also terminates DOSBox-X. Another method is the [F11/F12]+F combination mentioned in the Wiki. Some controls in those menus provide the same functionality as DOS commands, in which case the Mac user interface may be sometimes be more convenient to use. (For example, the menu item "DOS > Reported DOS version" is apparently equivalent to the DOS command "VER".) The "Save and restart" option of the Configuration tool does not restart the emulator if the program was started from a Terminal command line -- only if it was started from Finder. (The Terminal process window remains open.) DOS EXECUTABLES MIGRATED Three DOS executables have been migrated from this author's old hardware and are heavily used: - StereoShell 4.00 (MRE Software, 1991) - a directory tree navigator and file manager - Kedit 5.0 (Mansfield Software Group, 1992) - a text file editor based on the widely used IBM mainframe editor XEDIT; scriptable with KEXX (a dialect of REXX) - Turbo Pascal 5.5 (Borland International, 1989) - compiler for the Pascal language Three more DOS executables have been migrated from this author's old hardware and appear to be usable with at least some degree of success: - Infoplus 1.30S (Andrew Rossmann, 1990) - detailed reporting of "hardware" configuration - PCTools 4.22 (Central Point Software, 1988) - a file and disk utility - XTree Pro 1.0 (Executive Software, 1987) - a directory tree navigator and file manager - - - - -