lwc:flatpak:arsandbox

Creating and Using a flatpak of arsandbox

Creating and Using a flatpak of arsandbox

Debug

Fail and check

flatpak-builder --run build-dir-arsandbox org.arsandboxg.ARSandbox.yml sh

the --run flat causes flatpak-builder to ignore the build instructions in the yaml. Instead it will setup /app and /usr folders then execute the sh command given. (bash might be a better choice)

Now you can look around to figure out where files are so you can add the right stuff to the yml file

When debugging –run is your best friend

Offline

opening another terminal window after the fail and cding into the build-dir directory might show you the file structure but commands like make will not behave the same as they will use the host OS tools instead of the flatpak tools.

Create

heavily commented yaml file: org.arsandboxg.ARSandbox.yml

# yml for flatpak
# v1.0 John Harrison john.harrison@alum.mit.edu Dec-2025

# prep for flatpak:
# sudo apt install flatpak flatpak-builder
# flatpak install flathub org.freedesktop.Platform//24.08 org.freedesktop.Sdk//24.08

# to create: flatpak-builder --repo=repo --force-clean --state-dir=build-cache-arsandbox build-dir-arsandbox org.arsandboxg.ARSandbox.yml
# then bundle as one file: flatpak build-bundle repo arsandbox_g.flatpak org.arsandboxg.ARSandbox

app-id: org.arsandboxg.ARSandbox
runtime: org.freedesktop.Platform
runtime-version: '24.08' # latest stable Dec 2025
sdk: org.freedesktop.Sdk
command: SARndbox

finish-args:          # permissions i.e. "holes" in the sandbox
  - --share=ipc       # high-speed video data transfer via shared memory
  - --socket=x11      # access to X11
  - --socket=wayland  # access to Wayland
  - --device=all      # access to all devices including the Kinect USB and the GPU
  - --filesystem=host # allows file write to host filesystem so we can save config files

build-options:
  env:
    # where will we find the .pc (package config) files?

    # /usr/share/pkgconfig and /usr/lib/pkgconfig are "boilerplate" so always have those
    # these map to the flatpak SDK i.e. /var/lib/flatpak/runtime/org.freedesktop.Sdk OR
    # ~/.local/share/flatpak/runtime/org.freedesktop.Sdk depending on how Flatpak was installed

    # /app/lib/pkgconfig magically maps to /build-dir/arsandbox/files/lib/pkgconfig and
    # is required for libusb and vrui since those are built as part of the flatpak
    # when builds fail look for the .pc files inside this flatpak files directory
    PKG_CONFIG_PATH: /app/lib/pkgconfig:/usr/lib/pkgconfig:/usr/share/pkgconfig

modules:
  - name: libusb
    buildsystem: autotools # libusb had a configure.ac file which is a giveaway for autocools
                           # this basically means we follow the pattern: ./configure && make && make install
    config-opts:
      - --prefix=/app      # boilerplate. Without this make install would try to install into /usr/local
                           # which doesn't exist for a flatpak
      - --disable-static   # flatpak doesn't like static libraries apparently so consider this boilerplate
    sources:
      - type: git
        url: https://github.com/libusb/libusb.git
        tag: v1.0.26

  - name: vrui
    buildsystem: simple    # all we had to work with was a makefile so we need to give exact commands to build
    build-commands:
      # Run config to generate Config.h files:
      # libusb was installed in /app (see above)
      # libext defaults to /lib64 on 64 bit systems but flatpak uses /lib. libext is a custom name in vrui
      # you can find that custom name in BuildRoot/SystemDefinitions
      # installdir is boilerplate. Put everything in /app
      # SYSTEM_HAVE_LIBDBUS was to fix a comopiler error. This was used to inhibit the screensaver only
      # so it seemed not worth trying to fix the compiler error for this
      - make config LIBUSB1_BASEDIR=/app LIBEXT=lib SYSTEM_HAVE_LIBDBUS=0 INSTALLDIR=/app

      # Disable DC1394 (FireWire camera) support since it was giving errors in compile and we didn't need 1394.
      - sed -i 's/SYSTEM_HAVE_DC1394 = 1/SYSTEM_HAVE_DC1394 = 0/g' BuildRoot/Configuration.Vrui
      - sed -i 's/#define VIDEO_CONFIG_HAVE_DC1394 1/#define VIDEO_CONFIG_HAVE_DC1394 0/g' Video/Config.h

      # Build
      - make -j${FLATPAK_BUILDER_N_JOBS} LIBUSB1_BASEDIR=/app LIBEXT=lib SYSTEM_HAVE_LIBDBUS=0 INSTALLDIR=/app

      # Install
      - make install LIBUSB1_BASEDIR=/app LIBEXT=lib SYSTEM_HAVE_LIBDBUS=0 INSTALLDIR=/app
          
    sources:
      - type: git
        url: https://github.com/vrui-vr/Vrui.git
        branch: main

  - name: kinect
    buildsystem: simple
    # figure out the below make flags with `flatpak-builder --run build-dir-arsandbox org.arsandboxg.ARSandbox.yml sh`
    build-commands:
      - make VRUI_MAKEDIR=/app/share/Vrui-14.0/make VRUI_INCLUDEDIR=/app/include/Vrui-14.0 VRUI_LIBDIR=/app/lib/Vrui-14.0 LIBUSB1_BASEDIR=/app LIBEXT=lib INSTALLDIR=/app
      - make install VRUI_MAKEDIR=/app/share/Vrui-14.0/make VRUI_INCLUDEDIR=/app/include/Vrui-14.0 VRUI_LIBDIR=/app/lib/Vrui-14.0 LIBUSB1_BASEDIR=/app LIBEXT=lib INSTALLDIR=/app
    sources:
      - type: git
        url: https://github.com/vrui-vr/Kinect.git
        branch: main

  - name: arsandbox
    buildsystem: simple
    build-commands:
      # Run config first to generate Config.h
      - make config VRUI_MAKEDIR=/app/share/Vrui-14.0/make VRUI_INCLUDEDIR=/app/include/Vrui-14.0 VRUI_LIBDIR=/app/lib/Vrui-14.0 LIBUSB1_BASEDIR=/app LIBEXT=lib INSTALLDIR=/app
      
      # Patch Config.h to use dynamic configuration directory AND copy defaults if missing
      # if would be better if code was fix but for now we "soft patch"
      # note use of - l for list so yaml parser doesn't get confused with backslash n
      - |
        sed -i '1i #include <stdlib.h>\n#include <string>\n#include <sys/stat.h>\n#include <unistd.h>\nstatic std::string getConfigDir() {\n const char* xdg = getenv("XDG_CONFIG_HOME");\n std::string dir;\n if(xdg) dir = std::string(xdg) + "/SARndbox-5.0";\n else { const char* home = getenv("HOME"); if(home) dir = std::string(home) + "/.config/SARndbox-5.0"; else return "/app/etc/SARndbox-5.0"; }\n mkdir(dir.c_str(), 0755);\n std::string test = dir + "/SARndbox.cfg";\n if(access(test.c_str(), F_OK) != 0) { std::string cmd = "cp -n /app/etc/SARndbox-5.0/* " + dir; int ret = system(cmd.c_str()); (void)ret; }\n return dir;\n}' Config.h
      - sed -i 's|#define CONFIG_CONFIGDIR .*|#define CONFIG_CONFIGDIR getConfigDir().c_str()|' Config.h

      # Patch Water2WaterUpdateShader.fs to fix read-only variable assignment
      # really this should be fixed in the source code as well
      - sed -i 's/snowMelt=min(snowMelt,s);/float meltAmount=min(snowMelt,s);/g' share/Shaders/Water2WaterUpdateShader.fs
      - sed -i 's/dSnow=dSnow-snowMelt;/dSnow=dSnow-meltAmount;/g' share/Shaders/Water2WaterUpdateShader.fs
      - sed -i 's/dWater=dWater+snowMelt\/4.0;/dWater=dWater+meltAmount\/4.0;/g' share/Shaders/Water2WaterUpdateShader.fs

      # Build and Install
      - make VRUI_MAKEDIR=/app/share/Vrui-14.0/make VRUI_INCLUDEDIR=/app/include/Vrui-14.0 VRUI_LIBDIR=/app/lib/Vrui-14.0 LIBUSB1_BASEDIR=/app LIBEXT=lib INSTALLDIR=/app
      - make install VRUI_MAKEDIR=/app/share/Vrui-14.0/make VRUI_INCLUDEDIR=/app/include/Vrui-14.0 VRUI_LIBDIR=/app/lib/Vrui-14.0 LIBUSB1_BASEDIR=/app LIBEXT=lib INSTALLDIR=/app
    sources:
      - type: git
        url: https://github.com/vrui-vr/arsandbox.git
        branch: main

Create the repo

flatpak-builder --repo=repo --force-clean --state-dir=build-cache-arsandbox build-dir-arsandbox org.arsandboxg.ARSandbox.yml

put the finished build in a folder called repo
do not use any part of any previous build
provide a cache folder so flatpak-builder doesn't have to redownload stuff every build
give a temp directory for the build

bundle the repo as one file

flatpak build-bundle repo arsandbox_g.flatpak org.arsandboxg.ARSandbox

the name of file
app ID

Give user permission to access Kinect

sudo sh -c 'printf "# Kinect v1\nSUBSYSTEM==\"usb\", ATTR{idVendor}==\"045e\", ATTR{idProduct}==\"02b0\", 
     MODE=\"0666\"\nSUBSYSTEM==\"usb\", ATTR{idVendor}==\"045e\", ATTR{idProduct}==\"02ad\", 
     MODE=\"0666\"\nSUBSYSTEM==\"usb\", ATTR{idVendor}==\"045e\", ATTR{idProduct}==\"02ae\", 
     MODE=\"0666\"\nSUBSYSTEM==\"usb\", ATTR{idVendor}==\"045e\", ATTR{idProduct}==\"02c2\", MODE=\"0666\"\n\n# Kine
     v2\nSUBSYSTEM==\"usb\", ATTR{idVendor}==\"045e\", ATTR{idProduct}==\"02c4\", MODE=\"0666\"\nSUBSYSTEM==\"usb\",
     ATTR{idVendor}==\"045e\", ATTR{idProduct}==\"02d8\", MODE=\"0666\"\nSUBSYSTEM==\"usb\", ATTR{idVendor}==\"045e\
     ATTR{idProduct}==\"02d9\", MODE=\"0666\"\n" > /etc/udev/rules.d/55-kinect.rules'
sudo udevadm control --reload-rules && sudo udevadm trigger
# if Kinect is already plugged into the computer, unplug and replug

Usage

See list of commands inside flatpak: flatpak run --command=ls org.arsandboxg.ARSandbox /app/bin. Will return:

AlignPoints           EyeCalibrator       MeasurePoints             RunVRCompositor.sh  TransformCalculator
AlignTrackingMarkers  FindHMD             OculusCalibrator          SampleTrackerField  VRCompositingServer
CalibrateCameras      KinectServer        OnHMD                     SARndbox            VRDeviceDaemon
CalibrateProjector    KinectUtil          PrintInputDeviceDataFile  SARndboxClient      VruiSoundConfig
CalibrateTouchscreen  KinectViewer        RawKinectViewer           ScreenCalibrator    VruiSoundConfigTest
DeviceTest            MeasureEnvironment  RoomSetup                 TrackingTest        XBackground

Run Calibrate Projector utility: flatpak run --command=CalibrateProjector org.arsandboxg.ARSandbox
See what the Kinect sees: flatpak run --command=RawKinectViewer org.arsandboxg.ARSandbox
Run: flatpak run org.arsandboxg.ARSandbox
Run “low spec mode”: flatpak run org.arsandboxg.ARSandbox -wts 320 240 -ws 1.0 10 # reduce water grid size to 320x240 and reduce max steps per frame from 30 to 10

Table of Contents