dosbox-staging

This repository attempts to modernize the DOSBox codebase by using current development practices and tools, fixing issues, and adding features that better support today's systems.

Summary of differences compared to upstream

For developers

	dosbox-staging	DOSBox
Version control	Git	SVN
Language	C++11	C++031
SDL	2.0	1.2＊
CI	Yes	No
Static analysis	Yes2,3,4	No
Dynamic analysis	Yes	No
clang-format	Yes	No
Automated regression tests	No (WIP)	No

Feature differences

dosbox-staging does not support audio playback using physical CDs. Using CD Digital Audio emulation (loading CD music via cue sheets or mounting ISO images) is preferred instead.

Codecs supported for CD-DA emulation:

	dosbox-staging†	DOSBox SVN‡
Opus	Yes (libopus)	No
OGG/Vorbis	Yes (built-in)	Yes - SDL_sound 1.2 (libvorbis)5,＊
MP3	Yes (built-in)	Yes - SDL_sound 1.2 (libmpg123)5,＊,§
FLAC	Yes (built-in)	No§
WAV	Yes (built-in)	Yes - SDL_sound 1.2 (built-in)6,＊
AIFF	No	Yes - SDL_sound 1.2 (built-in)6,＊

^{＊- SDL 1.2 was last updated 2013-08-17 and SDL_sound 2008-04-20
† - 22.05 kHz, 44.1 kHz, 48 kHz; mono, stereo
‡ - 44.1 kHz stereo only
§ - Broken or unsupported in either SDL_sound or DOSBox}

Other differences:

	dosbox-staging	DOSBox SVN
Pixel-perfect mode	Yes (output=texturepp)7	N/A
OPL emulators	compat, fast, mame, nuked8	compat, fast, mame
CGA/mono support	Yes (machine=cga_mono)9	Only CGA with colour
Wayland support	Experimental (use SDL_VIDEODRIVER=wayland)	N/A

Development snapshot builds

Pre-release builds can be downloaded from CI build artifacts. Go to Linux, Windows or macOS, select the newest build and download the package linked in the "Artifacts" section.

You need to be logged-in on GitHub to access these snapshot builds.

Linux

Snapshots are dynamically-linked x86_64 builds, you'll need additional packages installed via your package manager.

Fedora

sudo dnf install SDL2 SDL2_net opusfile

Debian, Ubuntu

sudo apt install libsdl2-2.0 libsdl2-net-2.0 libopusfile0

Arch, Manjaro

sudo pacman -S sdl2 sdl2_net opusfile

Windows

A dosbox.exe file in a snapshot package is not signed, therefore Windows 10 might prevent the program from starting.

If Windows displays the message "Windows Defender SmartScreen prevented an unrecognised app from starting", you have two options to dismiss it:

1. Click "More info", and button "Run anyway" will appear.
2. Right-click on dosbox.exe, select: Properties → General → Security → Unblock

Windows packages are built for "x86" architecture (in practice it means i686).

macOS

Due to GitHub CI and Apple SDKs limitations, the snapshots work only on macOS Catalina (10.15).

dosbox-staging app bundle is unsigned - click on app with right mouse button, select "Open" and the dialog will show a button to run and unsigned app.

Build instructions

Linux, macOS, MSYS2, MinGW, other OSes

Read INSTALL file for a general summary about dependencies and configure options. Read build.md for the comprehensive compilation guide.

git clone https://github.com/dosbox-staging/dosbox-staging.git
cd dosbox-staging
./autogen.sh
./configure
make

You can also use a helper script ./scripts/build.sh, that performs builds for many useful scenarios (LTO, FDO, sanitizer builds, many others).

Visual Studio (2019 or newer)

First, you need to setup vcpkg to install build dependencies. Once vcpkg is installed and bootstrapped, open PowerShell, and run:

PS:\> .\vcpkg integrate install
PS:\> .\vcpkg install libpng sdl2 sdl2-net opusfile

These two steps will ensure that MSVC finds and links all dependencies.

Start Visual Studio, open file: vs\dosbox.sln and build all projects (Ctrl+Shift+B).

Interop with SVN

This repository is (deliberately) NOT git-svn compatible, this is a pure Git repo.

Commits landing in SVN upstream are imported to this repo in a timely manner, to the branches matching svn/* pattern. You can safely use those branches to rebase your changes, and prepare patches using Git format-patch for sending upstream (it is easier and faster, than preparing patches manually).

Other branch name patterns are also in use, e.g. vogons/* for various patches posted on the Vogons forum.

Git tags matching pattern svn/* are pointing to the commits referenced by SVN "tag" paths at the time of creation.

Additionally, we attach some optional metadata to the commits imported from SVN in the form of Git notes. To fetch them, run:

git fetch origin "refs/notes/*:refs/notes/*"

For some historical context of why this repo exists you can read Vogons thread.