fix: keep the Blender prefix world-readable, and report what actually failed

Three findings from running the sample end to end in a container, which is what
the new workflow does. All three were caught by that workflow rather than
reasoned about, which is the argument for having it.

The staged extraction introduced earlier in this branch made the prefix
root-only. mktemp -d creates a directory 0700 and mv preserves that, where the
mkdir it replaced took 0755 from the umask, so the artist could not traverse
/opt/blender and the add-on step failed with "Permission denied". Blender is a
system-wide install every user runs, so the staging directory is widened before
the move.

The add-on step then discarded Blender's output and reported only "failed to
enable the Blender add-on", which is how the permission error stayed invisible
for a run. Both the enable and the verify step now report what Blender said.

The library list the workflow installs was derived rather than guessed, and the
last of it took four rounds to find, because qtpy reports any failure to import
PySide6 as "No Qt bindings could be found" -- so a missing libglib, then a
missing libfontconfig, then the missing xcb platform libraries all present as a
missing PySide6 that is in fact bundled and present. The final list comes from
the closure of unresolved libraries across the installed tree under ldd. The
sample's README documents the whole set and how to diagnose it, since a customer
on a minimal image hits exactly this and the message points the wrong way.

Verified: exit 0 with all eight independent assertions passing -- Blender runs,
the add-on reads back from Blender's preferences as the artist, the CLI is on the
artist's login PATH, the profile has the right region, a non-empty monitor_id and
artist ownership, and auth status reports NEEDS_LOGIN -- and a second run also
exits 0, which exercises the prefix guard and staged extract on a re-run.

Signed-off-by: Stephen Crowe <6042774+crowecawcaw@users.noreply.github.com>

Author: crowecawcaw

.github/workflows/virtual_workstation_checks.yml

@@ -71,8 +71,22 @@ jobs:
     steps:
       # A container job has no git for actions/checkout, and the sample documents
       # a desktop environment as a prerequisite it deliberately does not install.
-      # Blender's X11 and GL libraries stand in for that here: this is CI setup,
-      # not something the sample should be doing on a real workstation.
+      # These libraries stand in for that desktop: this is CI setup, not something
+      # the sample should be doing on a real workstation.
+      #
+      # The list was derived empirically -- run the script, read what failed, and
+      # take the closure of unresolved libraries across the installed tree with
+      # ldd -- rather than guessed. Three groups, for two different consumers:
+      #
+      #   * Blender's own X11 and GL dependencies, without which it cannot exec.
+      #   * GLib, fontconfig, and freetype, for the PySide6 the submitter bundles.
+      #   * The xcb platform libraries that PySide6's Qt platform plugin needs.
+      #
+      # The Qt group is worth knowing about beyond CI: when any of it is missing,
+      # the add-on's import chain reaches qtpy, which reports the underlying
+      # ImportError as "No Qt bindings could be found" -- a message that sends you
+      # looking for a missing PySide6 that is in fact present and bundled. The
+      # sample's README documents this under Troubleshooting.
       - name: Install the prerequisites the sample documents
         run: |
           set -euo pipefail
@@ -81,7 +95,11 @@ jobs:
           apt-get install -y -qq --no-install-recommends \
             git sudo ca-certificates \
             libx11-6 libxi6 libxxf86vm1 libxfixes3 libxrender1 libxext6 \
-            libxkbcommon0 libsm6 libice6 libgl1 libegl1 libglu1-mesa libdbus-1-3
+            libxkbcommon0 libsm6 libice6 libgl1 libegl1 libglu1-mesa libdbus-1-3 \
+            libglib2.0-0 libfontconfig1 libfreetype6 \
+            libxkbcommon-x11-0 libxcb-cursor0 libxcb-icccm4 libxcb-image0 \
+            libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 libxcb-shape0 \
+            libxcb-xkb1
 
       - name: Check out repository
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

utility_scripts/virtual_workstation/README.md

@@ -174,6 +174,22 @@ Remove-Item -Recurse -Force "C:\Program Files\Blender"
 
 Runs interrupted after this point do not recur: Blender is now unpacked to a staging directory beside the prefix and moved into place, so the prefix only ever exists complete.
 
+**The add-on step fails with `qtpy.QtBindingsNotFoundError: No Qt bindings could be found`.** The bindings are present: the submitter bundles PySide6. That message is `qtpy` reporting an `ImportError` it could not attribute, and the real cause is a system library that PySide6 links against and this image does not have. On a minimal Ubuntu 22.04 image, this is the set:
+
+```console
+sudo apt-get install -y libglib2.0-0 libfontconfig1 libfreetype6 \
+    libxkbcommon-x11-0 libxcb-cursor0 libxcb-icccm4 libxcb-image0 \
+    libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 libxcb-shape0 libxcb-xkb1
+```
+
+To see the actual cause rather than the `qtpy` summary, run `ldd` over the bundled Qt and look for `not found`:
+
+```console
+ldd /opt/DeadlineCloudSubmitter/Submitters/Blender/python/modules/PySide6/QtCore.abi3.so | grep "not found"
+```
+
+Ignore the `libQt6*.so.6` entries there: those resolve within the bundle at load time. A full desktop environment provides all of these, which is why this only appears on an image that has none. It is the same class of failure as Blender's own missing X11 and GL libraries, which the script reports directly.
+
 **The Deadline Cloud menu is missing in Blender.** Add-ons register per user, so confirm the script ran for the account that is signing in. On Linux that is the second argument. On Windows it is the account that ran the script. To check, as that same user:
 
 ```console

utility_scripts/virtual_workstation/setup_workstation_linux.sh

@@ -254,6 +254,13 @@ tar -xJf "$WORK_DIR/$blender_archive" -C "$blender_staging" --strip-components=1
 [[ -x "$blender_staging/blender" ]] \
     || die "the Blender archive did not contain a blender executable"
 
+# mktemp -d creates the directory 0700 and mv preserves that, which would leave
+# every account but root unable to even traverse the prefix -- so the artist's
+# add-on step would fail with "Permission denied". Blender is a system-wide
+# install that every user runs, so widen it to the 0755 that mkdir would have
+# produced under the usual umask.
+chmod 755 "$blender_staging"
+
 # Replace any previous install so re-runs are clean. Only ever delete a directory
 # this script created: BLENDER_PREFIX is a constant an administrator edits, and
 # removing it unconditionally as root would destroy whatever it names.
@@ -340,18 +347,22 @@ log "submitter installed at $SUBMITTER_PREFIX"
 addon_script="$SUBMITTER_PREFIX/Submitters/Blender/add_submitter_to_pref.py"
 addon_path="$SUBMITTER_PREFIX/Submitters/Blender/python"
 
+# Capture the output and report it on failure. Discarding it leaves the operator
+# with "failed to enable the Blender add-on" and nothing to act on, when the
+# actual cause is in the message -- a prefix the artist cannot execute, say.
 log "enabling the Blender add-on for $WORKSTATION_USER"
-runuser -u "$WORKSTATION_USER" -- env HOME="$USER_HOME" \
-    "$BLENDER_PREFIX/blender" --background --python "$addon_script" \
-    -- --deadline_cloud_install_path "$addon_path" >/dev/null \
-    || die "failed to enable the Blender add-on"
+addon_output="$(
+    runuser -u "$WORKSTATION_USER" -- env HOME="$USER_HOME" \
+        "$BLENDER_PREFIX/blender" --background --python "$addon_script" \
+        -- --deadline_cloud_install_path "$addon_path" 2>&1
+)" || die "failed to enable the Blender add-on: $addon_output"
 
 # Confirm from Blender's preferences rather than trusting the exit code.
-runuser -u "$WORKSTATION_USER" -- env HOME="$USER_HOME" \
-    "$BLENDER_PREFIX/blender" --background --python-expr \
-    'import bpy, sys; sys.exit(0 if "deadline_cloud_blender_submitter" in bpy.context.preferences.addons.keys() else 1)' \
-    >/dev/null 2>&1 \
-    || die "the Blender add-on did not register in $WORKSTATION_USER's preferences"
+verify_output="$(
+    runuser -u "$WORKSTATION_USER" -- env HOME="$USER_HOME" \
+        "$BLENDER_PREFIX/blender" --background --python-expr \
+        'import bpy, sys; sys.exit(0 if "deadline_cloud_blender_submitter" in bpy.context.preferences.addons.keys() else 1)' 2>&1
+)" || die "the Blender add-on did not register in $WORKSTATION_USER's preferences: $verify_output"
 log "Blender add-on enabled"
 
 # ---------------------------------------------------------------------------