Compile from source

Compile from Source

Compiling Amiberry from source

Tip

Want to test the latest features without building? You can download the latest automated Development Builds (created from the master branch) which are built automatically for macOS and Linux.

Dependencies

Linux

You'll need the development version of the required packages. For example, on Debian-based distros:

  sudo apt install build-essential git cmake libsdl3-dev libsdl3-image-dev libflac-dev libmpg123-dev libpng-dev libmpeg2-4-dev libserialport-dev libportmidi-dev libenet-dev libpcap-dev libzstd-dev libcurl4-openssl-dev nlohmann-json3-dev libdbus-1-dev

On Distros that use RPM instead (e.g. Fedora):

  sudo dnf install gcc gcc-c++ git cmake SDL3-devel SDL3_image-devel flac-devel libmpg123-devel libpng-devel libmpeg2-devel libserialport-devel portmidi-devel enet-devel libpcap-devel libzstd-devel libcurl-devel json-devel dbus-devel

Or if you're using an Arch-based distro (e.g. Manjaro):

  sudo pacman -S base-devel cmake sdl3 sdl3_image flac mpg123 libmpeg2 libserialport portmidi enet libpcap zstd curl nlohmann-json

macOS

Under macOS, you will need to install the required libraries. For example by using Homebrew:

    brew install cmake sdl3 mpg123 sdl3_image flac libmpeg2 libserialport portmidi enet libpcap zstd dylibbundler nlohmann-json

Windows

Amiberry supports Windows x86_64 using MinGW-w64 (GCC). Dependencies are managed through vcpkg.

Prerequisites

• MinGW-w64 (GCC)
• CMake
• Ninja
• vcpkg

Setting up vcpkg

1. Clone and bootstrap vcpkg:

git clone https://github.com/microsoft/vcpkg.git C:\vcpkg
cd C:\vcpkg
.\bootstrap-vcpkg.bat

2. Set the VCPKG_ROOT environment variable to C:\vcpkg (or wherever you cloned it). You can set this as a system or user environment variable.

Building from the command line

$env:VCPKG_ROOT = "C:\vcpkg"
cmake --preset windows-release
cmake --build out/build/windows-release -j12

Building with CLion

CLion's bundled MinGW toolchain works well with Amiberry. After setting up vcpkg (see above):

1. Open the Amiberry project in CLion.

2. Go to Settings → Build, Execution, Deployment → CMake.

3. In the CMake options field, add:

-DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake -DVCPKG_TARGET_TRIPLET=x64-mingw-dynamic

Note

Use x64-mingw-dynamic for dynamic linking or x64-mingw-static for static linking, depending on your preference.

4. Make sure VCPKG_ROOT is set — either as a system environment variable, or added in CLion's run/debug configuration environment variables.

5. CLion should now be able to configure and build the project using its built-in CMake integration.

Clone with submodules

Amiberry uses git submodules for some dependencies (e.g. native file dialogs). Clone with --recursive to get everything:

  git clone --recursive https://github.com/BlitterStudio/amiberry.git

If you already cloned without --recursive, initialize the submodules separately:

  git submodule update --init --recursive

Note

Building without submodules still works — optional features like native OS file dialogs will be disabled and the built-in file browser is used instead.

Supported architectures

Amiberry builds on the following architectures:

• ARM64 (AArch64) — Full JIT support for maximum performance
• x86-64 (AMD64) — Full JIT support
• ARM 32-bit — JIT support
• RISC-V 64-bit — Interpreter only (no JIT)
• LoongArch64 — Interpreter only (no JIT)

The architecture is auto-detected by CMake. No special flags are needed.

Build Amiberry

Amiberry uses CMake to build. The following commands will create a build directory, configure the build, and then compile the source code:

  cmake -B build && cmake --build build

You can also use Ninja, if you prefer:

  cmake -B build -G Ninja && cmake --build build

CMake's default installation prefix is /usr/local/. To change this, specify a different prefix when invoking CMake. For example, to install under /opt, use:

  cmake -B build -G Ninja -DCMAKE_INSTALL_PREFIX=/opt && cmake --build build

Build time options

Amiberry has a few different options that can be found in the main CMakeLists.txt file. Some are disabled by default, as they are optional, others are enabled by default but can be turned off in order to build a minimal version with fewer external dependencies if the user wants.

The following options are enabled by default:

• USE_LIBSERIALPORT - Uses the libserialportfor serial port emulation
• USE_LIBENET - Use library enet for network emulation
• USE_PORTMIDI Use PortMidi for MIDI emulation
• USE_LIBMPEG2 - Use libmpeg2 for MPEG2 decoding (CD32 FMV)
• USE_UAENET_PCAP - Use libpcap for uaenet.device emulation

The following CMake options are disabled by default. You can choose to enable them, if you want to use them (note that some require extra libraries):

• USE_GPIOD - Use libgpiod to control GPIO LEDs (Power, HDD, Floppy). Only makes sense on boards that have GPIO pins (e.g. Raspberry Pi). You will obviously need the library installed as well, to make use of this.
• USE_DBUS - Enable D-BUS to control the emulator from another application. Useful if you have another front-end that you want to use, instead of Amiberry's own GUI.
• USE_OPENGL - Use the OpenGL back-end with shader support.
• USE_VULKAN - Use the Vulkan back-end for rendering (experimental). Mutually exclusive with USE_OPENGL — only one can be enabled at a time.
• WITH_OPTIMIZE - Generates the most optimal march and/or mcpu flags for your cpu.
• WITH_LTO - Uses Link Time Optimizations. Will take a lot of time. EXPERIMENTAL!

Debug build

By default, the build type is Release, which creates optimized binaries without debug symbols. If you want to change that to Debug (useful if you want to use a debugger and troubleshoot something), add this when invoking the first CMake command:

-DCMAKE_BUILD_TYPE=Debug

Local installation

After the build is finished, you can use the following command to install Amiberry locally in the default PREFIX directory (/usr/local/):

sudo cmake --install build

After installation, you may want to update the relevant desktop, mime, and man databases accordingly. This is not handled by CMake so you must do that yourself. For example (replace @CMAKE_INSTALL_PREFIX@ with what you gave CMAKE_INSTALL_PREFIX):

update-desktop-database
update-mime-database "@CMAKE_INSTALL_PREFIX@/share/mime"
gtk-update-icon-cache -f -t "@CMAKE_INSTALL_PREFIX@/share/icons/hicolor"

Packaging

There are currently several packaging options configured with CPack:

• TGZ (tar.gz) archive
• DragNDrop DMG image (macOS only)
• DEB package (Linux only)
• RPM package (Linux only)

By default, all the available packaging options for the platform will be built, unless you request a specific one. If you only want a specific one, use the -G <package> parameter. For example, the following will only build the DEB package on Linux:

cpack --config build/CPackConfig.cmake -G DEB

More documentation regarding packaging with CPack can be found here.