Build guide

86Box is built using CMake in combination with other build systems. The build actions are described in CMakeLists.txt files in most directories, which are the translated to the build system of choice by a CMake generator.

The following files are of particular interest:

  • ./CMakeLists.txt is the top level file, which defines the 86Box project and available configuration options;

  • ./src/CMakeLists.txt defines the main 86Box executable target

Toolchain files

Toolchain files are contained in the cmake directory. They define compiler flags and the 86Box-specific Release, Debug and Optimized build types.

It is not required to use the included toolchain files, but it is highly recommended to make sure your build is compiled with the same configuration as used by the rest of the team and our userbase.

The currently included files are:

  • flags-gcc.cmake contains the generic flags used by GCC-like compilers

    • flags-gcc-<arch>.cmake includes flags specific to builds for a given architecture

  • llvm-win32-<arch>.cmake defines the build environment for use with LLVM/clang and vcpkg on Windows

Toolchain files are consumed during the initial project generation stage by passing their path in the CMAKE_TOOLCHAIN_FILE variable, e.g.:

$ cmake … -D CMAKE_TOOLCHAIN_FILE=./cmake/flags-gcc-x86_64.cmake

Note

When using vcpkg, which uses its own toolchain file, the 86Box toolchain files must be chainloaded using the VCPKG_CHAINLOAD_TOOLCHAIN_FILE variable.

Presets

The CMakePresets.json file contains several common compilation options for 86Box:

Build name

Debug

Dev. branch

Optimized

regular

❌

❌

❌

development

❌

✅

❌

debug

✅

❌

❌

dev_debug

✅

✅

❌

optimized

❌

❌

✅

The presets are consumed during the initial project generation stage by using the --preset CMake command line option, e.g.:

$ cmake … --preset regular

Note

Presets require CMake 3.21 or newer.

Obtaining the source code

There are multiple ways to obtain the 86Box source code in order to build it:

  • Use the git command line. The utility needs to be installed and present in the search path.

    $ git clone https://github.com/86Box/86Box.git

  • Use GitHub Desktop, SourceTree, Git for Windows or other Git frontend on your host.

  • Download a ZIP file from GitHub and extract it. (not recommended)

Prerequisites

The build process requires the following tools:

  • CMake (>= 3.15)

  • pkg-config

  • libatomic

Development files for the following libraries are also needed:

  • FluidSynth

  • FreeType

  • libpng

  • libslirp

  • libsndfile

  • RtMidi

  • SDL2

  • OpenAL (by default) or FAudio (installing FAudio is optional on Windows)

  • Qt5 or Qt6 (optional, can be disabled)

Obtaining the dependencies

MSYS2

$ pacman -Syu $MINGW_PACKAGE_PREFIX-ninja $MINGW_PACKAGE_PREFIX-cmake $MINGW_PACKAGE_PREFIX-gcc $MINGW_PACKAGE_PREFIX-pkgconf $MINGW_PACKAGE_PREFIX-openal $MINGW_PACKAGE_PREFIX-freetype $MINGW_PACKAGE_PREFIX-SDL2 $MINGW_PACKAGE_PREFIX-zlib $MINGW_PACKAGE_PREFIX-libpng $MINGW_PACKAGE_PREFIX-rtmidi $MINGW_PACKAGE_PREFIX-fluidsynth $MINGW_PACKAGE_PREFIX-libslirp $MINGW_PACKAGE_PREFIX-libsndfile $MINGW_PACKAGE_PREFIX-qt5-static $MINGW_PACKAGE_PREFIX-qt5-translations $MINGW_PACKAGE_PREFIX-vulkan-headers

Note

The command installs the packages only for the currently used MinGW environment, therefore you will need to repeat the procedure for every target you plan to build for.

Ubuntu, Debian

$ sudo apt install build-essential cmake extra-cmake-modules pkg-config ninja-build libfreetype-dev libsdl2-dev libpng-dev libopenal-dev librtmidi-dev libfluidsynth-dev libsndfile1-dev qtbase5-dev qtbase5-private-dev qttools5-dev libevdev-dev libxkbcommon-dev libxkbcommon-x11-dev libslirp-dev

Arch

$ sudo pacman -Sy base-devel cmake extra-cmake-modules pkgconf ninja libfreetype sdl2 libpng openal rtmidi libslirp fluidsynth libsndfile qt5-base qt5-xcb-private-headers qt5-tools libevdev libxkbcommon libxkbcommon-x11 vulkan-devel

Fedora

$ sudo dnf groupinstall "C Development Tools and Libraries"
$ sudo dnf install cmake extra-cmake-modules pkg-config ninja-build freetype-devel SDL2-devel libatomic libpng-devel libslirp-devel libXi-devel openal-soft-devel rtmidi-devel fluidsynth-devel libsndfile-devel qt5-linguist qt5-qtconfiguration-devel qt5-qtbase-private-devel qt5-qtbase-static wayland-devel libevdev-devel libxkbcommon-x11-devel zlib-ng-compat-static

macOS (Homebrew)

$ brew install cmake ninja pkg-config freetype sdl2 libpng openal-soft rtmidi libslirp fluid-synth libsndfile qt@5

FreeBSD

$ pkg install pkgconf freetype-gl sdl2 libspng openal-soft rtmidi qt5 libslirp fluidsynth libsndfile

Note

If you get an error about linux/input.h, edit /usr/local/include/libevdev/libevdev.h to replace the linux/input.h reference with dev/evdev/input.h and try building again.

Building

Building 86Box can generally be condensed to the following steps:

  1. Generate the project. This generally involves invoking the following base command line with additional options according to the development environment:

    $ cmake -B <build directory> -S <source directory>

    Build directory is where the resulting binaries and other build artifacts will be stored. Source directory is the location of the 86Box source code.

    Toolchain files and presets are specified at this point by using the respective options.

    Other options can be specified using the -D option, e.g. -D NEW_DYNAREC=ON enables the new dynamic recompiler. See CMakeLists.txt in the root of the repository for the full list of available options.

  2. Build the project itself. This can be done by changing to the chosen build directory and invoking the chosen build system, or you can use the following universal CMake command:

    $ cmake --build <build directory>

    Appending the -jN option (where N is a number of threads you want to use for the compilation process) will run the build on multiple threads, speeding up the process some.

    Note

    If you make changes to the CMake build files, running the command will automatically regenerate the project. There is no need to repeat step 1 or to delete the build directory.

  3. If everything succeeds, you should find the resulting executable in the build directory. Depending on the build system, it might be located in some of its subdirectories.

Tip

The executable can be copied to a consistent location by running the following command:

$ cmake --install <build directory> --prefix <destination>

The emulator file should then be copied into a bin directory in the specified location.

Appending the --strip parameter will also strip debug symbols from the executable in the process.