Please provide a "beginner-friendly" documentation or FAQ or tutorial about linuxdeployqt

[KurtPfeifle]

I found linuxdeployqt being used in a number of .travis.yml recipes creating AppImages, in various projects around GitHub which release AppImage binaries.

However, SOME projects use linuxdeployqt and let it create the AppImage directly. OTHER projects initially run linuxdeployqt (doing "something", which I don't understand yet), but then call appimagetool to create the AppImage.

Also, I THINK linuxdeployqt-made AppImages do not support the embedding of the zsync2-update string into the AppImage, and hence will not be capable of making use of that mechanism for auto-updating.

I've read the README, but cannot fully grasp it, because it assumes...

• ...reader is familiar with the functionality of macdeployqt and when/how/why this may be used for macOS;
• ...reader is familiar with the problems linuxdeployqt tries to solve analogue to what macdeployqt does and how it works on macOS;
• ...reader is familiar with Qt and with the problems a user may encounter with it.

These assumptions are not necessarily true for every reader.

Please provide some additional documentation which answers the following items/questions:

1. Describe clearly (with examples), which problems may occur without the usage of linuxdeployqt. Which problem exactly does linuxdeployqt solve?

2. How exactly does linuxdeployqt work? ("It works on directory tree 'abc'. It first collects info about A, B, C... X, Y, Z." -- "It then removes X, Y, Z from directories 1, 2, 3. -- Finally, it does i., ii. and iii. -- The end result is ⍺, β, ɣ.")

3. Under exactly which conditions is it adviceable to make use of linuxdeployqt? Under which conditions does one not need to use it?

4. When is it preferable to create AppImages with the help of appimagetool? Has the prior use of linuxdeployqt then still have benefits?

5. What are the limitations of linuxdeployqt? (Does it or does it not support the creation of AppImages with the (relatively new) zsync2 auto-update mechanism?)

---

^{(Also, the name of this tool seems strange to me. The name suggests to me that it deploys Qt on Linux. Since the does not do this, the name is more confusing then helpful. Can't you think of a better name?)}

[probonopd]

I found linuxdeployqt being used in a number of .travis.yml recipes creating AppImages, in various projects around GitHub which release AppImage binaries.

Good. It's probably the easiest (and recommended) way for most applications that are compiled from source code using cmake, qmake, or make.

However, SOME projects use linuxdeployqt and let it create the AppImage directly. OTHER projects initially run linuxdeployqt (doing "something", which I don't understand yet), but then call appimagetool to create the AppImage.

In the normal case, you just run appimaged with the -appimage option on an AppDir and it will do the following:

• It checks if it can find the desktop and icon file, and determines the main executable from there
• It runs ldd on the executable to find out the library dependencies
• It copies the library dependencies into the AppDir
• It recursively runs ldd on the dependencies to find out more dependencies and also copies those
• It patches the binaries and libraries so that they can find dynamic libraries from paths relative to themselves
• In case of Qt 5 applications, it tries to figure out which plugins are needed, and bundles the required subset of Qt 5 plugins needed to run the application (additional ones can be specified manually)
• It puts a symlink to the main executable into the root of the AppDir, called AppRun
• In the end, it converts the AppDir to an AppImage (if running on Travis CI, it may also embed update information and generate a zsync file; see below)

In some rare cases, you need to modify the AppDir (as created by linuxdeployqt) before it is converted to an AppImage. In those cases, we usually extract the linuxdeployqt AppImage and invoke appimagetool manually (to do the last step above manually) after having done some modification to the AppDir (e.g., replaced the AppRun symlink with a custom bash script where needed).

Also, I THINK linuxdeployqt-made AppImages do not support the embedding of the zsync2-update string into the AppImage, and hence will not be capable of making use of that mechanism for auto-updating.

It should automatically detect if it is running on Travis CI, and it should automatically embed the required update information automatically if the environment variable GITHUB_TOKEN is set (which uploadtool also requires).

On OBS, all of this is done automatically too (but by OBS).

1. Describe clearly (with examples), which problems may occur without the usage of linuxdeployqt. Which problem exactly does linuxdeployqt solve?

linuxdeployqt bundles an application and its dependencies so that it can be distributed as an AppDir or an AppImage to users.

2. How exactly does linuxdeployqt work? ("It works on directory tree 'abc'. It first collects info about A, B, C... X, Y, Z." -- "It then removes X, Y, Z from directories 1, 2, 3. -- Finally, it does i., ii. and iii. -- The end result is ⍺, β, ɣ.")

Rough overview above. To make it much more detailed, we'd probably have to annotate the source code (which is really just an adoption of macdeployqt which, at the time, I didn't fully understand either - I just put in the Linux equivalents of Mac commands initially)

3. Under exactly which conditions is it adviceable to make use of linuxdeployqt? Under which conditions does one not need to use it?

There are different ways for how to create an AppImage described on https://github.com/AppImage/AppImageKit/wiki/Creating-AppImages#4-run-linuxdeployqt-on-your-qt-application.

Please let me know if the information there is unclear or incomplete.

4. When is it preferable to create AppImages with the help of appimagetool? Has the prior use of linuxdeployqt then still have benefits?

appimagetool takes a working AppDir and converts it into an AppImage. linuxdeployqt can help you put together such a working AppDir. As a last step, it can convert the AppDir to an AppImage for you using linuxdeployqt automatically (this happens when you invoke it using -appimage).

5. What are the limitations of linuxdeployqt? (Does it or does it not support the creation of AppImages with the (relatively new) zsync2 auto-update mechanism?)

It is not the option to go if you want to make AppImages of Python or Java applications or things like that.

(Also, the name of this tool seems strange to me. The name suggests to me that it deploys Qt on Linux. Since the does not do this, the name is more confusing then helpful. Can't you think of a better name?)

The name was chosen because it is a relatively close adoption of macdeployqt which "deploys Qt on macOS". That you can also use it to deploy non-Qt applications is a welcome side effect.

I hope these answers clarify it a bit; PRs/wiki edits welcome to incorporate this information in the appropriate places (where you would have expected to find them).

[yozachar]

Hi @probonopd thanks for that, but I'm still in blue, guess my knowledge on these needs an upgrade.

From what I infer, I think we can package apps (from source) in to AppImages using this tool. I've a forked a small repo https://github.com/joe733/cameo on which I want to experiment linuxdeployqt. I've cloned the fork and downloaded the linuxdeployqt.AppImage, but I cannot figure out how to organize or get things started. What I have in mind is to convert this source code into an AppImage. Can you please give a brief run down on what things I must do?

[probonopd]

Hi @joe733. https://github.com/joe733/cameo seems to be written in Python, so a tool specialized in bundling Python applications as an AppImage should be used.

https://github.com/AppImage/awesome-appimage#deployment-tools-for-python-applications