Improve First Launch Experience On Ubuntu

[AntonPalmqvist]

Version: gaffer-1.6.0.0-linux-gcc11
Third-party tools: None
Third-party modules: None

Description

While I understand that writing software that works for all distributions of Linux is near impossible, I do think that we can collectively improve the error messaging and also the installation instructions for specific distributions, especially popular ones such as Ubuntu.

Steps to reproduce

1. Launch Gaffer on a fresh install of Ubuntu 25.04 by following the instructions in the documentation.
2. Observe error messages

Debug log

Click to Expand

ERROR : unable to find "/opt/solidangle/arnold-7.4.4.0/include/ai_version.h".
ERROR : unable to find "/opt/pixar/RenderManProServer-26.3/include/prmanapi.h".
qt.qpa.plugin: Could not find the Qt platform plugin "wayland" in "/opt/gaffer-1.6.0.0-linux-gcc11/qt/plugins"
qt.qpa.plugin: From 6.5.0, xcb-cursor0 or libxcb-cursor0 is needed to load the Qt xcb platform plugin.
qt.qpa.plugin: Could not load the Qt platform plugin "xcb" in "/opt/gaffer-1.6.0.0-linux-gcc11/qt/plugins" even though it was found.
This application failed to start because no Qt platform plugin could be initialized. Reinstalling the application may fix this problem.

Available platform plugins are: vnc, xcb, offscreen, minimal, linuxfb.

Aborted (core dumped)

Despite the slew of errors, all that was needed was to run sudo apt install libxcb-cursor0 to install the missing package.

In my mind the two first errors about missing Arnold and RenderMan files should be warnings instead, as they're not required to run Gaffer.
The third line should also be a warning, as Wayland isn't required to run Gaffer either.
The fourth line was the most useful hint, as it included the package needed for Gaffer to run on Ubuntu. However, as mentioned above, only libxcb-cursor0 was needed and not xcb-cursor0

If desired, I could write up a PR with added info about the libxcb-cursor0 package, for Ubuntu users.

[AntonPalmqvist]

I realized now that the Arnold and RenderMan errors must've been from aliases that I had added, without having put the actual files in the correct location.

[johnhaddon]

I realized now that the Arnold and RenderMan errors must've been from aliases that I had added, without having put the actual files in the correct location.

Yeah, you should only see those errors if you have ARNOLD_ROOT and RMANTREE set respectively. This definitely needs some output so that folks can debug their setups when things aren't quite lined up right. Replacing the ERROR part with WARNING seems reasonable though, since Gaffer will still load.

If desired, I could write up a PR with added info about the libxcb-cursor0 package, for Ubuntu users.

This does sound useful, but I think I'd balance it against how clean/intrusive the implementation was. I'm not super keen on something hardcoded to Ubuntu, because the missing package problem isn't limited to that platform. Did you have any thoughts on what an implementation would look like?

[AntonPalmqvist]

Sorry, I meant I could write up a PR for the documentation over at https://github.com/GafferHQ/documentation with just a short mention about Ubuntu users potentially needing to install this package.

[johnhaddon]

Ah, I see! Yep, that sounds like it would be useful - thanks!

[murraystevenson]

Sorry, I meant I could write up a PR for the documentation over at https://github.com/GafferHQ/documentation with just a short mention about Ubuntu users potentially needing to install this package.

To avoid you starting off on the wrong foot, the https://github.com/GafferHQ/documentation repo is only used to host the documentation from each Gaffer release via GitHub Pages, and is updated automatically after each release. PRs for changes to the documentation itself would be made to https://github.com/GafferHQ/gaffer (this repo).

For further reference, here's a recent PR for a documentation update that added RenderMan instructions to the "Configuring Gaffer for Third-Party Tools" page.

[AntonPalmqvist]

Thank you for that! I've now created a PR here with my humble changes: #6589