What do you think about this paragraph I added?

You wanted to mention $APPDIR here, which points to the runtime mountpoint.

It's a good idea to put this on the bottom of the page, since this approach has significant drawbacks. Normally, this environment variable is only available when an application is actually run via the AppImage runtime. The environment variable would only be available in an extracted AppImage or an AppDir right before packaging if there is a suitable AppRun (script) that defines it.

Should we include an example script?

You wanted to mention $APPDIR here, which points to the runtime mountpoint.

Ah, I see that APPDIR would be right, not APPIMAGE for this case.

It's a good idea to put this on the bottom of the page, since this approach has significant drawbacks. Normally, this environment variable is only available when an application is actually run via the AppImage runtime. The environment variable would only be available in an extracted AppImage or an AppDir right before packaging if there is a suitable AppRun (script) that defines it.

I'm a bit confused. I'm interpreting this as two different things. 1. It's available by default during runtime of any appimage; 2. It's only available in an extracted appimage before packaging and only if there's a suitable AppRun script that defines it.

I've just tried using APPDIR with a small program I maintain. I inserted this code into main(), at the top:

  char *appdir = getenv("APPDIR");
  if (appdir != NULL)
    printf("%s\n", appdir);

I created an appimage with linuxdeploy. When I run it, the mountpoint is printed. I'm not using an AppRun script, just the symlink created by linuxdeploy. So my thinking is that if a developer had trouble using relative paths to data for example, they could simply do something like:

if getenv APPDIR == NULL
  use unmodified data path
else
  data = $APPDIR/usr/share/data...

And as far as I can tell, that would be robust. Please correct me if I'm missing something.

/cc @Jammyjamjamman

I think part of this PR should include some improvement here. The link to the binreloc repo works, but in its README, the link to the docs on how to actually use it is dead. Someone reported it a while ago but it hasn't been corrected. limbahq/binreloc#4 I've never used binreloc. Is it still stable? Is there a good site that has the docs on how to use it?

It's just a library that helps developers use paths relative to the current binary. Many GUI frameworks also include such facilities, a famous example is Qt's QCoreApplication::applicationDirPath() method.

Generally this section is quite outdated. We should include more real-world examples from common libs like Qt, Gtk+. The parent section already explains that resources must be located relative to the main binary (arguably the wording could be improved).

This is mostly done I think.

In places where I edited or added new content, I wrapped long lines because it's much easier for me to review and edit documents. In fact, many projects I've worked on have guidelines that state long lines should be wrapped around col 79 (or something similar). I hope that will be fine for the purposes of this PR.

Generally this section is quite outdated. We should include more real-world examples from common libs like Qt, Gtk+.

Any ones in particular you'd like added?

You'll see I removed all references to binreloc. As the binreloc project repo (that was linked in the docs here) wasn't updated since 2016, I couldn't find the API docs for it (just a lot of dead links), and it doesn't seem to be included in any LInux repos https://repology.org/project/binreloc/versions

For Gtk, the recommended approach would be to compile any external resources into the application wherever possible, as GResources.

You create a manifest file as a .gresource.xml file, and the glib-compile-resources tool can either compile it to a .gresource binary file, or (with --generate-source and --generate-header) it can output C code to compile into the application.

Whether resources come from a .gresource file loaded with g_resource_load() or are directly compiled in and registered by calling register_resource(), the contents can be accessed using g_resource_open_stream() / g_resources_lookup_data(), or by instantiating a GFile to a resource URL. (resource:///org/gtk/Example/data/splashscreen.png is the example their docs use.)

I don't believe Gtk offers any particular features for determining or using the application runtime location; their filesystem tools are mostly focused on things like standard XDG paths.

(It might be worth mentioning, too, that Qt also has the ability to use compiled-in resources: a .qrc file acts as the manifest, and their rcc compiler takes the place of glib-compile-resources in generating code for incorporation into the application itself. QFile, and any other Qt class that accepts file path strings, can be passed a string of the form ":/path/to/resource" to load a compiled-in resource instead.

The only exception is PyQt6, which dropped support for the Qt resource system. PyQt5 included a pyrcc5 which compiled resources into Python code, and Qt's rcc compiler now supports compiling resources into Python for use with Qt for Python 6.)

(I wrote that like Qt was aping GLib, but credit where credit is due: AFAIK Qt's resource system long preceded GResource, and was very likely a big part of the inspiration for its design. GResource didn't exist until Gio 2.32 in 2012, but Qt has had a resource system since Qt 4 (2005). There was even a much more limited predecessor system called qembed in Qt 3.)