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.

Build status

Code quality status

Summary of differences compared to upstream

For developers

	DOSBox Staging	DOSBox
Version control	Git	SVN
Language	C++17	C++03¹
SDL	>= 2.0.5	1.2^＊
Logging	Loguru for C++⁶	Yes, in-house class
Buildsystem	Meson or Visual Studio 2019	Autotools or Visual Studio 2003
CI	Yes	No
Static analysis	Yes^2,3,4,5	No
Dynamic analysis	Yes	No
clang-format	Yes	No
Development builds	Yes	No
Unit tests	Yes⁶	No
Automated regression tests	WIP	No

Feature differences

DOSBox Staging supports features not included in DOSBox SVN. Below is a detailed comparison of feature differences between DOSBox Staging and DOSBox SVN.

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)^6,＊
MP3	Yes (built-in)	Yes - SDL_sound 1.2 (libmpg123)^6,＊,§
FLAC	Yes (built-in)	No^§
WAV	Yes (built-in)	Yes - SDL_sound 1.2 (built-in)^7,＊
AIFF	No	Yes - SDL_sound 1.2 (built-in)^7,＊

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

Feature differences between release binaries (or unpatched sources):

Feature	DOSBox Staging	DOSBox SVN
Pixel-perfect mode	Yes: `output=openglpp` or `output=texturepp`	N/A
Resizable window	Yes: for all `output=opengl` modes	N/A
Relative window size	Yes: `windowresolution=small`, `medium`, or `large`	`windowresolution=X%`
Window placement	Yes: `windowposition = 0,0`, and more¹⁶	Manual placement
OPL emulators	compat, fast, mame, nuked⁸	compat, fast, mame
CGA/mono support	Yes: `machine=cga_mono`)⁹	Only CGA with colour
CGA composite modes	Yes: `machine=pcjr/tandy/cga` with hotkeys)	N/A
Wayland support	Experimental: use `SDL_VIDEODRIVER=wayland`	N/A
Modem phonebook file	Yes: `phonebookfile=<name>`	N/A
Autotype command	Yes¹⁰	N/A
Startup verbosity	Yes¹¹	N/A
GUS enhancements	Yes¹²	N/A
Raw mouse input	Yes: `raw_mouse_input=true`	N/A
FluidSynth MIDI	Yes¹³: FluidSynth 2.x	Only external synths
MT-32 emulator	Yes^＊: libmt32emu 2.4.2	N/A
Expanded S3 support	4 and 8 MiB of RAM¹⁴	2 MiB of RAM
Portable & layered conf	By default¹⁵	With`-userconf` and `-conf`
Translations handling	Bundled, see section 14 in README	With path to .lng file
ENet modem transport	Yes: serialport `sock:1` flag or `SERIAL.COM`¹⁷	N/A
Ethernet via [slirp]	Yes: See `[ethernet]` section in conf file	N/A
IDE support for CDROMs	Yes: See `-ide` flag in `IMGMOUNT.COM /help`	N/A
Networking in Win3.11	Yes: Via local shell¹⁸	Yes: bootable HDD image

^{＊- Requires original ROM files}

Stable release builds

Linux, Windows, macOS

Test builds / development snapshots

Links to the newest builds

Get the source

Clone the repository (one-time step):

git clone https://github.com/dosbox-staging/dosbox-staging.git

Build instructions

Read BUILD.md for the comprehensive compilation guide.

Linux, macOS

Install build dependencies appropriate for your OS:

# Fedora
sudo dnf install ccache gcc-c++ meson alsa-lib-devel libpng-devel \
                 SDL2-devel SDL2_net-devel opusfile-devel fluidsynth-devel \
                 mt32emu-devel libslirp-devel speexdsp-devel

# Debian, Ubuntu
sudo apt install ccache build-essential libasound2-dev libpng-dev \
                 libsdl2-dev libsdl2-net-dev libopusfile-dev \
                 libfluidsynth-dev libslirp-dev libspeexdsp-dev

# Install Meson on Debian-10 "Buster" or Ubuntu-20.04 and older
sudo apt install python3-setuptools python3-pip
sudo pip3 install --upgrade meson ninja

# Install Meson on Debian-11 "Bullseye" or Ubuntu-21.04 and newer
sudo apt install meson

# Arch, Manjaro
sudo pacman -S ccache gcc meson alsa-lib libpng sdl2 sdl2_net opusfile \
               fluidsynth libslirp speexdsp

# openSUSE
sudo zypper install ccache gcc gcc-c++ meson alsa-devel libpng-devel \
                    libSDL2-devel libSDL2_net-devel opusfile-devel \
                    fluidsynth-devel libmt32emu-devel libslirp-devel \
                    speexdsp

# macOS
xcode-select --install
brew install ccache meson libpng sdl2 sdl2_net opusfile fluid-synth libslirp speexdsp

Build and stay up-to-date with the latest sources

Checkout the main branch:

# commit or stash any personal code changes
git checkout main -f

Pull the latest updates. This is necessary every time you want a new build:
```
git pull
```
Setup the build. This is a one-time step either after cloning the repo or cleaning your working directories:
```
meson setup build
```
The above enables all of DOSBox Staging's functional features. If you're interested in seeing all of Meson's setup options, run: meson configure.
Compile the sources. This is necessary every time you want a new build:
```
meson compile -C build
```
Your binary is: build/dosbox

The binary depends on local resources relative to it, so we suggest symlinking to the binary from your PATH, such as into ~/.local/bin/ -- Have fun!

Windows - Visual Studio (2019 or newer)

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

PS:\> .\vcpkg integrate install

This step will ensure that MSVC can use vcpkg to build, find and links all dependencies.

Start Visual Studio and open file: vs\dosbox.sln. Make sure you have x64 selected as the solution platform. Use Ctrl+Shift+B to build all projects.

Note, the first time you build a configuration, dependencies will be built automatically and stored in the vcpkg_installed directory. This can take a significant length of time.

Windows (MSYS2), macOS (MacPorts), Haiku, others

Instructions for other build systems and operating systems are documented in BUILD.md. Links to OS-specific instructions: MSYS2, MacPorts, Haiku.

Imported branches, community patches, old forks

Commits landing in SVN upstream are imported to this repo in a timely manner, see branch svn/trunk.

svn/* - branches from SVN
forks/* - code for various abandoned DOSBox forks
vogons/* - community 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 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, (1, 2)

canadacow/dosbox-staging