===== Creating and Using a flatpak of arsandbox =====
==== Debug ====
=== Fail and check ===
<code>
flatpak-builder --run build-dir-arsandbox org.arsandboxg.ARSandbox.yml sh
</code>
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 ''cd''ing 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 ====
<hidden heavily commented yaml file: org.arsandboxg.ARSandbox.yml>
<code>
# 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</code>
</hidden>
=== Create the repo ===
<code>
flatpak-builder --repo=repo --force-clean --state-dir=build-cache-arsandbox build-dir-arsandbox org.arsandboxg.ARSandbox.yml
</code>
  - 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 ===
<code>
flatpak build-bundle repo arsandbox_g.flatpak org.arsandboxg.ARSandbox
</code>
  - the name of file
  - app ID
 
==== Give user permission to access Kinect ====
<code>
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
</code>

==== Usage ====
  * See list of commands inside flatpak: ''flatpak run --command=ls org.arsandboxg.ARSandbox /app/bin''. Will return:
<code>
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
</code>

  * 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''