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 features

For developers

Feature	Status
Version control	Git
Language	C++17
SDL	>= 2.0.5
Logging	Loguru for C++5
Buildsystem	Meson or Visual Studio 2022
CI	Yes
Static analysis	Yes1,3,4
Dynamic analysis	Yes
clang-format	Yes
Development builds	Yes
Unit tests	Yes6
Automated regression tests	WIP

For users

Feature	Description
CD-DA file codecs	Opus, OGG/Vorbis, MP3, FLAC, and WAV
Integer scaling	integer_scaling = vertical or horizontal; replaced "pixel-perfect" mode7
Resizable window	Yes
Relative window size	windowresolution = small, medium, or large config setting
Window placement	windowposition config setting16
OPL emulator	Nuked OPL, a highly accurate (YMF262, CT1747) emulator 8
CGA/mono support	machine = cga_mono and monochrome_palette config settings9
CGA composite modes	For machine = pcjr, tandy, and cga; toggleable via hotkeys
Wayland support	Experimental: use SDL_VIDEODRIVER=wayland
Modem phonebook file	phonebookfile config setting
Raw mouse input	raw_mouse_input config setting
AUTOTYPE command	Yes10
MORE command	Yes21
Startup verbosity	Yes11
GUS enhancements	Yes12
FluidSynth MIDI	Built-in13; via FluidSynth 2.x (SoundFonts not included)
MT-32 emulator	Built-in; via libmt32emu 2.4.2 (requires user-supplied ROM files)
Expanded S3 support	4 and 8 MB of RAM14
Portable & layered conf	By default15
Translations handling	Bundled, see section 14 in README
ENet modem transport	serialport sock:1 flag or SERIAL.COM17
Ethernet via [slirp]	See [ethernet] config section
IDE support for CD-ROMs	See -ide flag in IMGMOUNT.COM /help
Networking in Win3.11	Via local shell18
Audio filters	See *_filter config settings
Audio reverb and chorus	See reverb config setting and MIXER.COM /help
Audio stereo crossfeed	See chorus config setting and MIXER.COM /help
AdLib Gold emulation	Via oplmode = opl3gold; emulates the surround add-on module too19
Master audio compressor	compressor config setting20
Dual/multi-mouse input	See [mouse] config section
ReelMagic support	See [reelmagic] config section

Stable release builds

Linux, Windows, macOS

Test builds / development snapshots

Development 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.

DOSBox Staging has the following library dependencies:

Package (libname)	Min Version	Provides feature	Presence	Meson-wrap	VCPKG	repo availability
FluidSynth (fluidsynth)	2.2.3	General MIDI playback	Optional	yes	yes	common
Google Test+Mock (gmock)	1.8.0	Framework for unit testing (development)	Optional	yes	yes	common
IIR (iir1)	1.9.3	Audio filtering	Mandatory	yes	yes	rare
libpng (libpng)	n/a	PNG-encoding of screen captures	Optional	yes	yes	very common
Munt (libmt32emu)	2.5.3	Roland MT-32 and CM-32L playback	Optional	yes	yes	rare
Opus File (opusfile)	n/a	CDDA playback for Opus-encoded track files	Mandatory	yes	yes	common
SDL 2.0 (sdl2)	2.0.5	OS-agnostic API for video, audio, and eventing	Mandatory	yes	yes	common
SDL_net 2.0 (sdl2-net)	2.0.0	Network API for emulated serial and IPX	Optional	yes	yes	common
slirp (libslirp)	4.6.1	Unprivileged virtual TCP/IP stack for Ethernet	Optional	yes	yes	less-common
SpeexDSP (speexdsp)	n/a	Audio resampling	Mandatory	yes	yes	common
Tracy Profiler (tracy)	n/a	Event profile (development)	Optional	yes	yes	rare
Zlib (zlib)	1.2.11	ZMBV video capture	Optional	yes	yes	very common

Linux, macOS

Install build dependencies appropriate for your OS:

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

# Debian, Ubuntu
sudo apt install ccache build-essential libasound2-dev libatomic1 libpng-dev \
                 libsdl2-dev libsdl2-image-dev libsdl2-net-dev libopusfile-dev \
                 libfluidsynth-dev libslirp-dev libspeexdsp-dev libxi-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_image sdl2_net \
               opusfile fluidsynth libslirp speexdsp libxi pkgconf

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

# Void Linux
sudo xbps-install -S SDL2-devel SDL2_net-devel alsa-lib-devel \
                     fluidsynth-devel libiir1-devel libmt32emu-devel \
                     libpng-devel libslirp-devel opusfile-devel \
                     speexdsp-devel libatomic-devel libXi-devel

# NixOS 
# With Home Manager on home.nix (Recommended Permanent Installation)
home.packages = [ pkg-config gcc_multi cmake ccache SDL2 SDL2_net \ 
                  fluidsynth glib gtest libGL libGLU libjack2 libmt32emu libogg \ 
                  libpng libpulseaudio libslirp libsndfile meson ninja opusfile \
                  libselinux speexdsp stdenv alsa-lib xorg.libXi irr1 ]

# Note: the same package list will work with environment.systemPackages 
# on configuration.nix

# macOS
xcode-select --install
brew install cmake ccache meson libpng sdl2 sdl2_image sdl2_net opusfile \
     fluid-synth libslirp pkg-config python3 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 (2022 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, Nix0S, others

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

Imported branches, community patches, old forks

Upstream commits 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/*"

Website & documentation

Please refer to the documentation guide before making changes to the website or the documentation.