README.osmesa

Run apkenv on you Desktop Linux system
======================================

Tested with Ubuntu 22.04 and Ubuntu 24.04 (which has 64-bit time_t for armhf).

Tested on Linux amd64, WSL2 amd64 (no sound, no MSAA), Linux aarch64.

This is VERY slow (OSMesa software rendering inside QEMU userspace emulation),
but it provides a way to test/run apkenv from a x86_64 GNU/Linux system.

For GLES 1.1 games, there's now a --serialize-gles switch that will send
the GL calls to the host UI process, so no software rasterization is involved
there. This isn't implemented for GLES 2.0, and there's some shortcomings in
general for GLES 1.1 games, but so far it works quite well.

Install cross-compiler and qemu userspace emulation:

    sudo apt install -y g++-12-arm-linux-gnueabihf qemu-user-binfmt \
        python3-mako meson ninja-build yacc flex \
        libsdl2-dev libao-dev libsdl1-mixer-dev

Make sure the loader can be found:

    sudo ln -s /usr/arm-linux-gnueabihf/lib/ld-linux-armhf.so.3 /usr/lib/ld-linux-armhf.so.3

Prepare Mesa off-screen OpenGL renderer build:

    mkdir -p deps
    cd deps
    wget https://archive.mesa3d.org/mesa-22.3.4.tar.xz
    tar xvf mesa-22.3.4.tar.xz
    cd mesa-22.3.4
    patch -p1 < ../../platform/osmesa/mesa-22.3.4-disable-kms-drm.patch

Build and install Mesa (in deps/mesa-22.3.4):

    env LD_LIBRARY_PATH=/usr/arm-linux-gnueabihf/lib meson builddir \
        -Dosmesa=true -Dgallium-drivers=swrast -Dvulkan-drivers=[] \
        -Ddri3=disabled -Dprefix=$PWD/builddir/install \
        -Dplatforms=[] -Dglx=disabled -Degl-native-platform=surfaceless \
        --cross-file ../../platform/osmesa/cross.txt
    ninja -C builddir install

Prepare and build zlib (starting from the checkout dir again):

    mkdir -p deps
    cd deps
    wget https://www.zlib.net/zlib-1.3.1.tar.gz
    tar xvf zlib-1.3.1.tar.gz
    cd zlib-1.3.1
    env CC=arm-linux-gnueabihf-gcc-12 ./configure --prefix=$(pwd)/install/
    make install

Build apkenv:

    make V=1

Run it (use --serialize-gles for GLES 1.1 games to have acceptable performance):

    LD_LIBRARY_PATH=deps/mesa-22.3.4/builddir/install/lib:/usr/arm-linux-gnueabihf/lib \
        qemu-arm ./apkenv --serialize-gles io.thp.trg2.android-1.apk