• Visual Boy Advance - M
  • System Requirements
  • Building
  • Visual Studio Code Support
  • Dependencies
  • CMake Options
  • Contributing

Visual Boy Advance - M

Our Discord server is here.

Game Boy and Game Boy Advance Emulator

The forums are here.

Windows and Mac builds are in the releases tab.

Nightly builds for Windows and macOS are at https://nightly.visualboyadvance-m.org/.

PLEASE TEST THE NIGHTLY OR MASTER WITH A FACTORY RESET BEFORE REPORTING ISSUES

Your distribution may have packages available as well, search for visualboyadvance-m or vbam.

It is also generally very easy to build from source, see below.

If you are having issues, try resetting the config file first, go to Help -> Factory Reset.

System Requirements

Windows XP+, macOS or Linux.

Older and weaker systems may not be able to run the higher level xBRZ and ScaleFX scalers.

For Windows XP install:

• DirectX June 2010 Redist
• Visual C++ runtimes all-on-one pack for January 202

Building

The basic formula to build vba-m is:

git clone https://github.com/visualboyadvance-m/visualboyadvance-m
cd visualboyadvance-m

./installdeps # On Linux, macOS or MSYS2

mkdir build
cd build
cmake .. -DCMAKE_BUILD_TYPE=Release -G Ninja
ninja

If ./installdeps does not work, you may need to install dependencies manually, see below for the list. ./installdeps also works on MSYS2.

For builds using automatically downloaded vcpkg packages for dependencies on macOS or Linux, make sure PowerShell Core is installed, and use:

cmake .. -DVCPKG_TARGET_TRIPLET=**<SYSTEM>** -DCMAKE_BUILD_TYPE=Release -G Ninja

, where SYSTEM is one of:

• x64-linux,
• arm64-macos,
• x64-macos,

. On Windows, vcpkg is the default and that is handled automatically.

If you are in an MSYS2 shell, the MSYS2 package dependencies installed via ./installdeps are the default, unless you pass `-DVCPKG_TARGET_TRIPLET= which is one of:

• x64-mingw-static (for MINGW64, UCRT64 or CLANG64),
• x32-mingw-static (for Windows XP builds using a MINGW32 toolchain.)

You can download a MINGW32 toolchain here and extract it to C:\msys64 or wherever your MSYS2 is installed. After which C:\msys64\mingw32 has to be in your PATH for the vcpkg build.

A VCPKG_ROOT is automatically created as a sibling of the project directory, unless you set it to something else in your environment.

Visual Studio Code Support

Make sure the C/C++ and CMake Tools extensions are installed.

Add the following to your settings.json:

{
    "cmake.configureOnOpen": true,
    "cmake.preferredGenerators": [ "Ninja" ]
}

.

Dependencies

You will need the following:

• C++ and C compiler and binutils,
• CMake.

And the following development libraries,

all platforms, required:

• zlib,
• Gettext and gettext-tools,
• SDL3 or SDL2,
• wxWidgets,
• bzip2,
• xz/lzma,

optional:

• FFmpeg,
• OpenAL-Soft,
• Lua,
• FAudio,
• Vulkan,

on Linux you will also need:

• glibc-devel,
• mesa,
• GTK3,
• XOrg,
• Wayland,

on macOS you will need MoltenVK for Vulkan support.

CMake Options

The CMake code tries to guess reasonable defaults for options, but you can override them, for example:

cmake .. -DCMAKE_BUILD_TYPE=Release -DENABLE_LINK=NO -G Ninja

. Here is the list:

CMake Option	What it Does	Defaults
ENABLE_SDL	Build the SDL port	OFF - Win, ON - rest
ENABLE_WX	Build the wxWidgets port	ON
ENABLE_LINK	Enable GBA/GB linking functionality	ON
ENABLE_LIBRETRO	Build the libretro core	ON
BUILD_TESTING	Build the tests	ON
UPSTREAM_RELEASE	Do some release tasks, like codesigning and making zips	OFF
TRANSLATIONS_ONLY	Build only the translations.zip and nothing else	OFF
ENABLE_LTO	Compile with Link Time Optimization	ON for release build
VCPKG_BINARY_PACKAGES	Download/use vcpkg binary packages	ON - Win, OFF - rest
VCPKG_TARGET_TRIPLET	Enable vcpkg download/use of vcpkg binary packages for that triplet	ON - Win, OFF - rest
VCPKG_SOURCE_PACKAGES	Enable builds of vcpkg deps when binary packageas are not available	ON - Win, OFF - rest
NO_VCPKG_UPDATES	Do not update vcpkg ports from either binaries or source	OFF
VBAM_STATIC	Try to link as many libraries statically as possible	ON - Win/MSYS2 or OFF
DISABLE_MACOS_PACKAGE_MANAGERS	Do not use the detected brew/Nix/MacPorts on macOS	OFF
ENABLE_SDL3	Use SDL3 not SDL2	ON if detected
ENABLE_GENERIC_FILE_DIALOGS	Use generic file open/selection dialogs on macOS	OFF
DISABLE_OPENGL	Disable OpenGL support	OFF
ENABLE_DEBUGGER	Enable the debugger	ON
ENABLE_LUA	Enable Lua scripting support for wxWidgets port	ON
ENABLE_ASAN	Use -fsanitize=address for GCC/Clang Debug builds	OFF
ENABLE_BZ2	Enable bzip2 .bz2 archive support	ON
ENABLE_LZMA	Enable lzma .xz archive support	ON
ENABLE_LIRC	Enable LIRC support	OFF
ENABLE_FFMPEG	Enable ffmpeg A/V recording	ON
ENABLE_ONLINEUPDATES	Enable online update checks	ON (release builds)
ENABLE_GBA_LOGGING	Enable extended GBA logging	ON
ENABLE_OPENAL	Enable openal-soft sound output for wxWidgets	ON
ENABLE_XAUDIO2	Enable xaudio2 sound output for wxWidgets (Windows only)	ON
ENABLE_FAUDIO	Enable faudio sound output for wxWidgets	ON
ENABLE_VULKAN	Enable Vulkan video output	ON
ENABLE_DIRECT3D	Enable Direct3D 9 support (Windows only)	ON - Win
ENABLE_DIRECT3D12	Enable Direct3D 12 support (Windows only)	ON - Win

Note for distro packagers, we use the CMake module GNUInstallDirs to configure installation directories.

On Linux or macOS, to use a different version of wxWidgets, set wxWidgets_CONFIG_EXECUTABLE to the path to the wx-config script you want to use.

Contributing

See the Developer Manual.