Building & Installing

Get binaries from CI

Staging branch is continuously built in GitHub CI for Linux (x86_64/arm64/riscv64/i386), Windows (x86_64/arm64/i386), MacOS (x86_64/arm64), FreeBSD (x86_64), OpenBSD (x86_64).

Installing package for your distribution

Officially maintained AUR package exists (Staging rvvm-git).

Installing build dependencies

Debian based (Ubuntu, Mint, etc)

sudo apt install git build-essential pkgconf libx11-dev libxext-dev libwayland-dev libxkbcommon-dev

Arch

sudo pacman -S git base-devel libx11 libxext wayland libxkbcommon

MacOS

Obtain SDL2 dmg installer, or install using your package manager

sudo brew install sdl2 || sudo port install libsdl2

Building RVVM

git clone https://github.com/LekKit/RVVM
cd RVVM
make
cd release.linux.x86_64
./rvvm_x86_64 -h

The release directory and binaries are suffixed with the host OS / arch by default.

Installing

make install PREFIX="pkg"

NOTE: The make install target is provided to be used by your distribution packaging mechanism via setting DESTDIR and PREFIX variables. Refer to your distribution documentation on how to set this up.

Do not perform a system-wide install directly, unless you know what you're doing.

You may install locally for your user, the maintenance is up to you then:

make install PREFIX=~/.local

Building on Windows

The same steps may be replicated using a MinGW build environment, such as w64devkit, mingw-w64 or llvm-mingw, which bin directory has to be added to PATH. Prefer msvcrt toolchain variant.

The make command should be substituted to mingw32-make:

cd RVVM-staging
mingw32-make

Cross-compilation

To cross-compile RVVM for a different host arch / os, simply pass the C cross-compiler executable as CC variable:

make CC="x86_64-w64-mingw32-gcc"

make CC="zig cc -target aarch64-macos"

make CC="riscv64-linux-gnu-gcc"

make CC="x86_64-unknown-redox"

Extended build system use

The build system supports disabling/enabling features via useflags (For debugging, disabling optional libraries, binary size reduction).

Invoke make help target to show available useflags and targets.

List of build configuration flags

Build paths

BUILDDIR # Build directory, defaults for example to `release.windows.x86_64`

Target options (Deduced automatically except in rare edge cases)

CC           = cc         # C compiler
CXX          = c++        # C++ compiler
PKG_CONFIG   = pkg-config # Package config tool (pkg-config)
CPPFLAGS     =            # User-supplied additional C/C++ preprocessor flags
CFLAGS       =            # User-supplied additional C/C++ optimization/warning flags
LDFLAGS      =            # User-supplied additional linker flags
OS           =            # Target operating system
ARCH         =            # Target architecture
CC_BRAND     =            # Compiler brand (gcc/clang/cosmocc/tcc...)
CC_VERSION   =            # Compiler version
GIT_DESCRIBE =            # Git version as produced by `git describe --tags --always --long --dirty`

Compile options

USE_LTO         = 1 # Use Link-Time Optimizations
USE_LIB         = 1 # Build shared libraries
USE_LIB_STATIC  = 0 # Build static libraries
USE_LIB_SHARING = 1 # Link to shared project libraries
USE_DEBUG       = 0 # Optimized build with debug info
USE_DEBUG_FULL  = 0 # Full debug build without optimizations

Warning / Static analysis / Sanitizer options

USE_WARNS    = 4 # Warning level
USE_ANALYZER = 0 # Use Clang Static Analyzer / GCC static analyzer
USE_UBSAN    = 0 # Use UndefinedBehaviorSanitizer
USE_ASAN     = 0 # Use AddressSanitizer
USE_TSAN     = 0 # Use ThreadSanitizer
USE_MSAN     = 0 # Use MemorySanitizer (Clang-only)

List of project feature useflags

CPU features

USE_RV32 = 1 # Support riscv32imacb guests
USE_RV64 = 1 # Support riscv64imacb guests
USE_FPU  = 1 # Support FPU extensions
USE_RVV  = 0 # Support Vector extension

Usability features

USE_GUI     = 1 # Enable guest display GUI
USE_X11     = 1 # Enable X11 GUI backend - Picked by per-platform basis
USE_WAYLAND = 1 # Enable Wayland GUI backend - Picked by per-platform basis
USE_SDL     = 2 # Enable SDL GUI backend - Picked by per-platform basis
USE_NET     = 1 # Enable networking support
USE_SOUND   = 0 # Enable sound support
USE_GDBSTUB = 1 # Support debugging the guest via GDB remote protocol

Board features

USE_FDT  = 1 # Enable Flattened Device Tree automatic generation
USE_VFIO = 1 # Support PCIe VFIO pass-through on Linux hosts

Infrastructure

USE_INFRA_TESTS = 0 # Build infrastructure tests
USE_LIBS_PROBE  = 0 # Probe libraries in runtime instead of linking - Enabled in CI
USE_LOCK_DEBUG  = 1 # Runtime lock debugging & locking debug info
USE_ISOLATION   = 1 # Process isolation via seccomp/pledge
USE_JNI         = 1 # Enable JNI support in librvvm

Acceleration

USE_JIT = 1 # Just-in-time translation - Enabled by default on x86_64, arm64, riscv64
USE_KVM = 0 # WIP

Misc toggles for debugging host platform/compiler issues

USE_NO_STACKTRACE = 0 # Disable post-mortem crash stacktraces
USE_NO_DLIB       = 0 # Disable dynamic library probing via dlsym()/GetProcAddress()
USE_STDIO         = 0 # Use non-threaded stdio backend for disk IO (Instead of Win32/POSIX)
USE_SELECT        = 0 # Use select() event interface for networking (Instead of epoll/kqueue)

USE_SOFT_FPU_WRAP = 0 # Wrap native floating-point types into bitcasted representation - Enabled by default on i386 / m68k
USE_SOFT_FPU_FENV = 0 # Emulate FPU exceptions (Note this isn't soft-fp, and still fairly fast)

USE_NO_THREAD_LOCAL = 0 # Disable THREAD_LOCAL attribute usage
USE_NO_BUILD_ASSERT = 0 # Disable build-time assertions
USE_NO_RANDSTRUCT   = 0 # Disable struct randomization
USE_NO_ALIGN_TYPE   = 0 # Disable type alignment
USE_NO_SRC_OPT      = 0 # Disable per-source manual optimization level
USE_NO_FUNC_OPT     = 0 # Disable per-function manual optimization level
USE_NO_PREFETCH     = 0 # Disable __builtin_prefetch()
USE_NO_LIKELY       = 0 # Disable __builtin_expect()
USE_NO_FORCEINLINE  = 0 # Disable force inlining
USE_NO_NOINLINE     = 0 # Disable force un-inlining
USE_NO_SLOW_PATH    = 0 # Disable slow_path attribute
USE_NO_FLATTEN      = 0 # Disable flatten_calls attribute

USE_NO_GNU_ATOMICS   = 0 # Disable GNU __atomic, even if determined to be supported
USE_NO_C11_ATOMICS   = 0 # Disable C11 <stdatomic.h>, even if determined to be supported
USE_NO_SYNC_ATOMICS  = 0 # Disable GNU __sync, even if determined to be supported
USE_NO_WIN32_ATOMICS = 0 # Disable Win32 Interlocked atomics, even if determined to be supported
USE_NO_LIBATOMIC     = 0 # Disable libatomic fallback, falling back to global-lock atomics

Example:

make USE_NET=0 USE_SDL=2 USE_VFIO=0 USE_LIB_STATIC=1

Building RVVM using CMake

For some developers and environments it might be more convenient to use CMake:

git clone https://github.com/LekKit/RVVM
cd RVVM
cmake -S. -Bbuild
cmake --build build --target all
cd build
./rvvm -h

CMake build system supports same useflags as Make, but with a slightly different syntax:

cmake -S. -Bbuild -DUSE_WAYLAND=OFF

It is also possible to build on Windows using CMake + MSVC, but it's recommended to use GCC/Clang toolchains due to better optimizations and coverage.