mirror of
https://github.com/86Box/docs.git
synced 2026-02-22 01:25:34 -07:00
Rewrite the build guide (#11)
* Rewrite the build guide * Fix code block indentation * OpenAL is not needed anymore * Formatting changes + code block fix * Change wording, `--toolchain` is relatively new * Simplify the MSYS2 setup with `$MINGW_PACKAGE_PREFIX` * Small formatting fix
This commit is contained in:
David Hrdlička
GitHub
@@ -1,39 +1,173 @@
|
||||
Build guide
|
||||
===========
|
||||
Follow these steps to compile 86Box from source:
|
||||
|
||||
1. Install the `MSYS2 <https://www.msys2.org/>`_ environment. The rest of the guide will refer to the directory that you install it to (``C:\msys32`` or ``C:\msys64`` by default) as the MSYS2 root.
|
||||
86Box is built using `CMake <https://cmake.org/>`_ 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.
|
||||
|
||||
2. Launch your MSYS2 environment using the `MSYS2 MinGW 32-bit` shortcut. If you do not wish to use the shortcut, launch it using the `mingw32.exe` executable in the MSYS2 root.
|
||||
The following files are of particular interest:
|
||||
|
||||
3. Once launched, you should update the environment:
|
||||
.. code-block:: bash
|
||||
* ``./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
|
||||
|
||||
$ pacman -Syu
|
||||
Toolchain files
|
||||
---------------
|
||||
|
||||
You may need to do this twice, just follow the on-screen instructions. Please re-run the command periodically to keep the environment up-to-date.
|
||||
Toolchain files are contained in the ``cmake`` directory. They define compiler flags and the 86Box-specific ``Release``, ``Debug`` and ``Optimized`` build types.
|
||||
|
||||
4. Run the following command to install all of the dependencies:
|
||||
.. code-block:: bash
|
||||
|
||||
$ pacman -S gdb make git mingw-w64-i686-toolchain mingw-w64-i686-openal mingw-w64-i686-freetype mingw-w64-i686-SDL2 mingw-w64-i686-zlib mingw-w64-i686-libpng mingw-w64-i686-rtmidi
|
||||
It is not required to 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.
|
||||
|
||||
5. Once the environment is fully updated and all dependencies are installed, change directory to ``src``:
|
||||
.. code-block:: bash
|
||||
|
||||
$ cd path/to/86Box/src
|
||||
The currently included files are:
|
||||
|
||||
6. Start the actual compilation process:
|
||||
.. code-block:: bash
|
||||
* ``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
|
||||
|
||||
$ make -f win/Makefile.mingw
|
||||
|
||||
``make`` does not run in parallel by default. Use the ``-j`` switch to specify the number of parallel threads, such as ``-j4`` for 4 threads. You should not exceed your system's thread (logical processor) count, as that uses more resources for little to no gain.
|
||||
* ``llvm-win32-<arch>.cmake`` defines the build environment for use with LLVM/clang and vcpkg on Windows
|
||||
|
||||
8. If compilation succeeded (which it almost always should), the ``86Box.exe`` executable will be in the ``src`` directory.
|
||||
Toolchain files are consumed during the initial project generation stage by passing their path in the ``CMAKE_TOOLCHAIN_FILE`` variable, e.g.:
|
||||
|
||||
9. In order to test your fresh build, replace the ``86Box.exe`` in your current 86Box environment with your freshly-built one. If you do not have a pre-existing 86Box environment, download the latest successful build from the `86Box Jenkins <https://ci.86box.net>`_, and the latest ROM set from `the roms repository <https://github.com/86Box/roms>`_.
|
||||
.. code-block:: bash
|
||||
|
||||
10. Enjoy using and testing the emulator! :)
|
||||
$ cmake … -D CMAKE_TOOLCHAIN_FILE=./cmake/flags-gcc-x86_64.cmake
|
||||
|
||||
If you encounter issues at any step or have additional questions, please join the IRC channel or the appropriate channel on our Discord server and wait patiently for someone to help you.
|
||||
.. 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:
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
|
||||
* - Build name
|
||||
- Debug
|
||||
- New dynarec
|
||||
- Dev. branch
|
||||
- Optimized
|
||||
* - ``regular``
|
||||
- ❌
|
||||
- ❌
|
||||
- ❌
|
||||
- ❌
|
||||
* - ``debug``
|
||||
- ✅
|
||||
- ❌
|
||||
- ❌
|
||||
- ❌
|
||||
* - ``experimental``
|
||||
- ✅
|
||||
- ✅
|
||||
- ✅
|
||||
- ❌
|
||||
* - ``optimized``
|
||||
- ❌
|
||||
- ❌
|
||||
- ❌
|
||||
- ✅
|
||||
|
||||
The presets are consumed during the initial project generation stage by using the ``--preset`` CMake command line option, e.g.:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ 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.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ 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``
|
||||
|
||||
Development files for the following libraries are also needed:
|
||||
|
||||
* FreeType
|
||||
* libpng
|
||||
* RtMidi
|
||||
* SDL2
|
||||
* FAudio (optional on Windows)
|
||||
* Qt5 or Qt6 (optional, can be disabled)
|
||||
|
||||
Obtaining the dependencies
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
MSYS2
|
||||
"""""
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ pacman -Syu $MINGW_PACKAGE_PREFIX-ninja $MINGW_PACKAGE_PREFIX-cmake $MINGW_PACKAGE_PREFIX-gcc $MINGW_PACKAGE_PREFIX-pkg-config $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-qt5-static $MINGW_PACKAGE_PREFIX-qt5-translations
|
||||
|
||||
.. 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
|
||||
""""""""""""""
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ sudo apt install build-essential cmake extra-cmake-modules pkg-config libfreetype-dev libsdl2-dev libpng-dev libopenal-dev librtmidi-dev libfaudio-dev qtbase5-dev qttools5-dev libevdev-dev
|
||||
|
||||
|
||||
macOS (Homebrew)
|
||||
""""""""""""""""
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ brew install freetype sdl2 libpng openal-soft rtmidi faudio qt@5
|
||||
|
||||
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:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ 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:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ 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:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ 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.
|
||||
Reference in New Issue
Block a user