Skip to content

Commit

Permalink
Add some troubleshooting informations to readme.txt
Browse files Browse the repository at this point in the history
  • Loading branch information
maron2000 committed Jan 2, 2025
1 parent 3b65f1e commit 6783a24
Show file tree
Hide file tree
Showing 2 changed files with 52 additions and 6 deletions.
41 changes: 35 additions & 6 deletions contrib/macos/readme.txt
Original file line number Diff line number Diff line change
Expand Up @@ -5,22 +5,51 @@ Welcome to DOSBox-X, a cross-platform DOS emulator based on the DOSBox project.

This is an official DOSBox-X macOS package, which should run natively on the recent versions of macOS such as macOS Monterey (12), Big Sur (11), and Catalina (10.15). Both SDL1 and SDL2 binaries (in .app format) are provided in the macOS package, in the directories named "dosbox-x" and "dosbox-x-sdl2" respectively inside the zip file. While the SDL1 version is the default version, the SDL2 version may be preferred over the SDL1 version for certain features (particularly related to input handling) such as touchscreen input support. You can select either SDL1 or SDL2 version according to your preference, or just run the SDL1 version if you are not sure.

There are two ways to run DOSBox-X in macOS, either from the Finder or from the command-line (Terminal):
DOSBox-X Quick start
====================

* From the Finder, go to the directory where the macOS zip package is downloaded, you will see a folder name which is the same as the file name of the downloaded zip package. Inside this folder you will see "dosbox-x" (SDL1) and "dosbox-x-sdl2" (SDL2). Go to either one and click the program "dosbox-x" to start DOSBox-X. If you see a dialog asking you to select a folder, please select one which will then become your DOSBox-X working directory. You can choose to save this folder after you select one so that the folder selection dialog will no show up again next time, or let DOSBox-X show the folder selection dialog every time you run it from the Finder.
Using the Finder app, go to the folder where the macOS zip package is downloaded, and click the zip package. Then the package will be unzipped and you will see a folder with the same name as the package. Both SDL1 and SDL2 binaries (in .app format) are provided in the folders named dosbox-x and dosbox-x-sdl2 respectively inside the zip file.

* From the Terminal, go to the directory where the macOS zip package is downloaded, you will see a folder name which is the same as the file name of the downloaded zip package. Starting from this folder, use "cd" command to go to the directory where the DOSBox-X executable is located. For SDL1 build, type "cd dosbox-x/dosbox-x.app/Contents/MacOS", and for SDL2 build, type "cd dosbox-x-sdl2/dosbox-x.app/Contents/MacOS". Run DOSBox-X with "./dosbox-x" and you will see the DOSBox-X window.
There are three ways to run DOSBox-X in macOS, either from Launchpad, Finder, and Command-line (Terminal).

In case the DOSBox-X binary does not run on your macOS system, you can try execute the following commands from the Terminal *once* in the directory that the zip package is extracted (where you see two directories named "dosbox-x" and "dosbox-x-sdl2"):
* Install and launch DOSBox-X from Launchpad
In either dosbox-x or dosbox-x-sdl2 folders, you can find an app named dosbox-x. Drag and drop the app to the Applications folder to install DOSBox-X to Launchpad.

xattr -cr dosbox-x/dosbox-x.app dosbox-x-sdl2/dosbox-x.app
chmod +x dosbox-x/dosbox-x.app/Contents/MacOS/dosbox-x dosbox-x-sdl2/dosbox-x.app/Contents/MacOS/dosbox-x
* Launch DOSBox-X from Finder application
Instead of installing DOSBox-X to Launchpad as mentioned above, you can double-click the dosbox-x app to start DOSBox-X from the Finder application.

* Launch DOSBox-X from command-line (Terminal)
Starting from the unzipped folder mentioned above, use cd command to go to the directory where the DOSBox-X executable is located. For SDL1 build, type cd dosbox-x/dosbox-x.app/Contents/MacOS, and for SDL2 build, type cd dosbox-x-sdl2/dosbox-x.app/Contents/MacOS. Run DOSBox-X with ./dosbox-x and you will see the DOSBox-X window.

Troubleshooting
===============

- I get a dialogue stating “The app is not from the Mac App Store”

You need change your settings to allow launching apps from known developers.
Confirm "Privacy & Security" in the macOS Users Guide for details.

Choose Apple menu > System Settings, then click Privacy & Security in the sidebar. (You may need to scroll down.)
Go to Security, then click Open.
Click the pop-up menu next to “Allow applications from”, then choose App Store & Known Developers.
You should see a message mentioning launching "DOSBox-X" was blocked. Click Open Anyway.
Enter your login password, then click OK.

- I get "dosbox-x" is damaged and can't be opened error

You should be able to solve the problem by running the following command once in the Terminal.

Using the Terminal app, go to the unzipped folder of the macOS zip package. (You should find two folders dosbox-x and dosbox-x-sdl2)
Run xattr -cr .

Further Information
===================
Please visit the DOSBox-X homepage for the latest information about DOSBox-X:
https://dosbox-x.com/ or http://dosbox-x.software/

Also, some useful information such as install and build instructions can be found in the official README file
https://github.com/joncampbell123/dosbox-x?tab=readme-ov-file#

For a complete DOSBox-X user guide, including common ways to configure DOSBox-X and its usage tips, please visit the DOSBox-X Wiki:
https://dosbox-x.com/wiki

Expand Down
17 changes: 17 additions & 0 deletions contrib/windows/installer/readme.txt
Original file line number Diff line number Diff line change
Expand Up @@ -18,11 +18,28 @@ To change to the drive mounted like above, type "C:". If everything went fine, D

Hint: DOSBox-X supports different video output systems for different purposes. By default it uses the Direct3D output, but if you desire the pixel-perfect scaling feature for improved image quality you may want to select the openglpp output ("OpenGL perfect"). Also, if you use text-mode DOS applications and/or the DOS shell frequently you probably want to select the TrueType font (TTF) output to make the text screen look much better by using scalable TrueType fonts.

Troubleshooting
===============

- Choosing the appropriate build for your Windows version
Modern Windows users (7 and after) should use the standard (non-XP, non-lowend) builds but may try the non-standard builds if you prefer, although officially not supported.
Windows 9x/NT4/2000 users should use the MinGW lowend 9x builds (32-bit SDL1 only).
Windows XP users must use the XP compatible installer with "XP" in the file name, which includes Visual Studio XP builds and the 32-bit MinGW low-end builds. Note that not all features are available in the MinGW low-end builds, currently Slirp support is known to be missing. You also need to install the DirectX runtime or DOSBox-X will complain you're missing XInput9_1_0.dll. XP compatible builds works in ReactOS as well, but support is considered experimental.
Windows Vista users can use the XP installer or standard (non-XP) Visual Studio builds, because standard (non-XP) installer doesn't work in Vista. MinGW dropped support for XP/Vista, so install the 32-bit low-end builds from the XP compatible installer if you prefer MinGW builds.

- Joystick support for SDL1 builds
Regarding Joystick support, the SDL1 builds requires XInput compatible devices. If your joystick is not Xinput compatible, you may want to try the SDL2 builds or DirectInput to XInput wrappers such as XOutput or Xbox 360 controller emulator.
XOutput: https://github.com/csutorasa/XOutput
Xbox 360 controller emulator: https://www.x360ce.com/

Further Information
===================
Please visit the DOSBox-X homepage for the latest information about DOSBox-X:
https://dosbox-x.com/ or http://dosbox-x.software/

Also, some useful information such as install and build instructions can be found in the official README file
https://github.com/joncampbell123/dosbox-x?tab=readme-ov-file#

For a complete DOSBox-X user guide, including common ways to configure DOSBox-X and its usage tips, please visit the DOSBox-X Wiki:
https://dosbox-x.com/wiki

Expand Down

0 comments on commit 6783a24

Please sign in to comment.