appimage / docs.appimage.org Goto Github PK

After some successfully built AppImages:

• (regular Qt+QML App) https://github.com/llamaret/MystiQ/releases/tag/continuous
• (Retro game wrote in Java) https://www.opencode.net/azubieta/planetmule-appimage
• the project source includes other working recipes such as VLC, gnome-calculator, KCalc, wget and echo.

I guess it's time to document it. So I was wondering whether you prefer to have this documentation as part of doc.appimage.org or just add a reference to it?

https://docs.appimage.org/packaging-guide/native-binaries.html

Example:

# run linuxdeploy and generate an AppImage
> ./linuxdeploy-x86_64.AppImage --appdir AppDir --init-appdir

But the current version of linuxdeploy doesn't have --init-appdir option!

We need a better section on resource lookups. The section in question is very specific. However it is generally a good idea to look up resources relative to the main binary, and one doesn't require binreloc for it.

Generally it should be named something like "Look up resources in a way that supports relocation" or so.

CC aardappel/treesheets#130

Why was my carefully crafted content moved to "Other resources"?
I disagree with this. Please keep URLs constant, don't move my stuff to "Other resources".
I need to be able to link to stuff under URLs that don't change, and I don't want "other-resources" to be part of the URL.

Thanks!

Continuation of AppImage/AppImageKit#59

ok2cqr/cqrlog#110 (comment)

I'm sorry but I'm giving this up. After 12 hours of my daily work I'm trying to create just simple app image without any extra dependecies like mysql, libhamlib, xplanet etc. I found documentation but it's tons of information but there is no simple step by step how to. I'm sorry, but I'm not interesting about any internal functions, not yet. I just wanted to create simple image from cqrlog.AppDir directory produced by make DESTDIR='cqrlog.AppDir' with a desktop file and icon. No way without reading MB of documentation and manuals how it works internally. Maybe I'm too tired for this. I'm sorry.

We should have a simple copy&paste example as the first thing in the manual. All the details can follow thereafter for those who are really interested.

I feel with the author. He does not care about how AppImage works internally, he just wants to get an AppImage made as fast as possible without having to learn a lot about AppImage.

https://twitter.com/freakboy3742/status/1161149221812072449

I have been told that AppImage is the new hotness for Linux Apps.
I have been able to download and run AppImages.
What I can’t find?

HOW DO INSTALL THE DAMN TOOLS TO BUILD MY OWN APPIMAGES?

A bright, shiny penny for anyone who can point me at the page of docs.

Most of the tools we use to make AppImages are, well, AppImages, and hence do not need to be installed.

Ok… and how was I meant to know that? Point me at the page of documentation that says “These tools are all avaialble as AppImages from , and can be safely downloaded and executed directly.

For example:

“To build an AppImage from a .yml description file, simply run bash -ex ./pkg2appimage recipes/XXX.yml”.

Excellent. Now where does pkg2appimage come from?

The high-level tools are mostly from third parties and not from the AppImage project itself:

• linuxdeployqt (for compiled applications, both QT and others): https://github.com/probonopd/linuxdeployqt/releases/continuous
• linuxdeploy (plugin-based alternative that can also package e.g., Python applications using a Python Conda plugin): https://github.com/linuxdeploy/linuxdeploy/releases/continuous
• The plugin mentioned: https://raw.githubusercontent.com/TheAssassin/linuxdeploy-plugin-conda/master/linuxdeploy-plugin-conda.sh
• electron-forge (a tool to build Electron-based apps, it has AppImage building capabilities built in): https://github.com/electron-userland/electron-forge/releases
• pkg2appimage (a script for converting existing deb packages to AppImage; "last resort" if you can't use one of the tools above): https://raw.githubusercontent.com/AppImage/pkg2appimage/master/pkg2appimage

Our tool is running "under the hood" but if you really want you could use it directly, too:

• appimagetool (low-level tool, normally not used directly): https://github.com/AppImage/AppImageKit/releases/continuous

OMFG I cannot begin to tell you how much those docs don’t help.

For example: Riddle me this: Why, in multiple pages of documentation, there is no mention of how to install the toolchains?

If you mean with "toolchain" the compilers and such, we don't cover those because AppImage is just a container format that executes whatever you put inside it (think of it as a fancy self-mounting filesystem image). Just like CD-ROM authoring tools don't explain how to make the files that go into a CD-ROM, we don't go at length on how to make the files that go into an AppImage.
If you mean with "toolchain" the tools to turn binaries into AppImages, I hope the links above point you into the correct places.

Let us know if you are stuck, AppImage developers are on #AppImage on irc.freenode.net and are usually helpful in solving almost any challenge (just be a bit patient since we do this in our free time).

https://docs.appimage.org/packaging-guide/from-source/native-binaries.html#bundling-resources-into-the-appdir currently says "At the moment, AppImages are provided for x86/i386 and x86_64/amd64 architectures, as other platforms cannot be targeted properly on the build service. The tool itself should support all major platforms, including ARM. You can compile linuxdeploy yourself to test it. Contributions adding new platforms welcome!".

However looking at the current linuxdeploy releases, armhf and aarch64 downloads are also available 🙂 So the documentation needs a small update.

https://github.com/AppImage/docs.appimage.org/blob/master/source/packaging-guide/manual.rst

The AppRun file can be a script or executable. It sets up required environment variables such as $PATH and launches the payload application. You can write your own, but in most cases it is easiest (and most error-proof) to use a precompiled one from this repository.

I assume under "this repository" should be link, otherwise it's confusing.

The current instructions are not valid anymore and could lead to break the system.

'libfuse2' can live along fuse3 but we should not attempt to install the package 'fuse' nor to do all the rest with groups/modprobe...

Tested with a fresh 22.04, the only required step is:

sudo apt install libfuse2

If the users follow "blindly" the current instructions, they could think the format is responsible of the damages!

From: https://github.com/AppImage/docs.appimage.org/blob/master/source/packaging-guide/distribution.rst

Must run on the oldest still-supported Ubuntu LTS release (currently Ubuntu 14.04)

That should be 16.04 :)

https://github.com/AppImage/appimage.github.io/blob/master/README.md apparently has already been updated. 😃

I don't know whether there are further inconsistencies. Thanks.

Document --appimage-portable-home on https://github.com/AppImage/docs.appimage.org/blob/master/source/user-guide/portable-mode.rst.

Show an example using --appimage-portable-home.

Make clear that --appimage-portable-home and --appimage-portable-config are mutually exclusive (one should only use one of them, not both).

Maybe only document --appimage-portable-home because the other one seems to confuse people.

Hi there, i want to create an AppImage from Source of the projects
DOSBox-X
m64p-netplay-server

Trying to read the documentation in :
https://docs.appimage.org/packaging-guide/converting-binary-packages/pkg2appimage.html

Looks like just works with debs packages

And trying to read this another doc :
https://docs.appimage.org/packaging-guide/from-source/native-binaries.html

I don't understand this example :

# get the source code
> git clone https://github.com/linuxdeploy/QtQuickApp.git
> cd QtQuickApp

# create out-of-source build dir and run qmake to prepare the Makefile
> mkdir build
> cd build
> qmake ..

# build the application on all CPU cores
> make -j$(nproc)

# use make install to prepare the AppDir
> make install INSTALL_ROOT=AppDir

In which moment the AppDir was created ? i specify this example because m64p-netplay-server must be compile against to qmake (qt5.8)

I just need a very specific instructions for example
1 - Download
2 - Create this Directory Structure
3 - Create this basefile.yml
4 - Use the tool (1) this way
5 - change the permissions & Test the generated AppImage.

I have found the list of desktop entries introduced for AppImage purposes, and I think this list is not full.

I have integrated some packages using libappimage and in created desktop entry are entries not listed in docs:

[Desktop Entry]
Name=Auryo (2.5.4.503)
Exec=/home/pawel/Downloads/Auryo-2.5.4.AppImage
Terminal=false
Type=Application
Icon=appimagekit_28f0b030a2d65b08dddd1e5b5b60587e_auryo
StartupWMClass=Auryo
X-AppImage-Version=2.5.4.503
Comment=Listen to SoundCloud\u00ae from the comfort of your desktop. Use keyboard shortcuts to navigate through your music. Be more productive.
MimeType=x-scheme-handler/auryo;
Categories=Audio;
TryExec=/home/pawel/Downloads/Auryo-2.5.4.AppImage
X-AppImage-Old-Icon=auryo
X-AppImage-Old-Name=Auryo
X-AppImage-Identifier=28f0b030a2d65b08dddd1e5b5b60587e

At all contributors:

This project has no clear licensing for its contents. I would like to make these docs available under the terms of the CC-By 4.0 Intl license (a rather liberal license).

I need every author with significant contributions to agree on this. Please answer to this issue whether it is okay for you to license your contributions under this license, or if you want to have them removed again.

• @probonopd contributed some initial Markdown documents which were later converted to reST, as well as a few pages.
• @Taz8du29 converted most of the Markdown pages to the superior reST, with a few fixes and other minor contributions.
• @aferrero2707 provided some fixes and other smaller contributions
• @Inventitech contributed one paragraph on how to update applications in AppImageHub

The remaining contributors mainly fixed typos and syntactical errors. I assume it is no problem copyright wise to license these, as they are, in comparison to the remaining works, insignificant changes. However, I highlight you so you can have a look yourself, since I think that is good style. @claell @asashnov @zhmars @fboender @daquexian @dandelionred @alexmyczko @Trilarion

Please provide feedback until May 31, this issue should be sorted out very soon.

https://docs.appimage.org/

Some users request "offline formats" which allow for downloading the docs to read them while not connected to the Internet.

Sphinx allows for generating PDF/ePub files, and it shouldn't be very much of a problem to generate those in our build system and publish them along with our HTML pages.

We need to put a comment there, though, which warns users that the information might get outdated. Since we don't version our docs, you can't really tell when docs have changed, so the files should at least have the date of generation or so (and maybe the short commit hash) in their filename.

When following the FUSE troubleshooting steps, the docs say to do

> sudo modprobe -v fuse

but the author assumes this works, and does not explain how to proceed in case of a response of

modprobe: ERROR: ../libkmod/libkmod.c:586 kmod_search_moddep() could not open moddep file '/lib/modules/4.4.0-43-Microsoft/modules.dep.bin'
modprobe: FATAL: Module fuse not found in directory /lib/modules/4.4.0-43-Microsoft

As you may have suspected, this is the result when following your guide on Ubuntu as installed on WSL, where unfortunately modprobe and kernel modules in general are not supported. Up till this point, nothing in the docs has indicated that using WSL means AppImages will not work at all ever.

Suggestion to improve the docs would be to either indicate up front, e.g. as one of the linux flavours, that WSL does not support AppImages.

By extension, it would be nice if the guide for using an AppImage without fuse would explain which file to run after --appimage-extract, since I now have a directory full of files, many of them executable, but none clearly named after the program I want to run.

https://twitter.com/freakboy3742/status/1160385448012763136

My litmus test is can I copy-paste steps and have a working build in less than 10 lines of script/code. New user/on boarding experience is so critical.

How stringent is the sandbox?
What filesystem can they access? How can access be given to data or configuration directories?
What network to they have access to? Is the hostname/ip/routing any different from native applications?
How can an application from inside an appimage run another application installed on the system (appimaged or native)?

As of 0134 UTC, 10 May 2023, https://docs.appimage.org and https://appimage.org are raising SSL errors due to an invalid certificate.

Hi,

I would like to issue a couple of PRs to add examples on how to create AppImages.

Would you be open to adding an examples section ? I can add a section for it in the PRs.

Thanks!

This is following on from AppImage/AppImageKit#916

What is the current self update procedure and can this be enabled when the Appimage is first built.
Thanks

Your SSL certificate expired today 23/12/2019. Looks like your lets-encrypt script to renew it isn't triggering in time or stopped working.

I am also located in Australia if that helps since we are day ahead date wise.

The environment variables APPDIR, APPIMAGE, ARGV0 etc. should be documented in the Packaging Guide.

CC AppImage/AppImageKit#852 (comment)

This document is currently work in progress. Contributions welcome!

When will this be removed, and the docs will no more be "work in progress"?

Some AppImages on https://appimage.github.io/ seems to not be on https://www.appimagehub.com/ (I searched for ImHex), so I take it they are two different stores.
The documentation seems to refer to your store as "AppImageHub", and link to https://github.com/AppImage/AppImageHub , but it redirects to https://github.com/AppImage/appimage.github.io

My question is : What is https://www.appimagehub.com/ and how does it relate to https://appimage.github.io/ ?

Reminder to self:

Add information about how to use the tempate based on SLE 12-SP4 for a lower glibc version:

https://build.opensuse.org/package/show/home:rfparedes:branches:OBS:AppImage:Templates:SLE:12-SP4/AppImageTemplate

to

https://github.com/AppImage/docs.appimage.org/blob/master/source/packaging-guide/hosted-services/opensuse-build-service.rst

Reference:
fish-shell/fish-shell#6475 (comment)

Currently we are using reStructuredText for docs.appimage.org but some users (including myself) strongly prefer Markdown.

reStructuredText offers more powerful features but also has an entirely unfamiliar (at least to me) syntax, resulting in me avoiding to touch the documentation altogether.

MyST could be the solution:

The MyST-parser is a Sphinx parser for the MyST markdown language. When you use it, Sphinx will know how to parse content files that contain MyST markdown (by default, Sphinx will assume any files ending in .md are written in MyST markdown).

It allows one to use directives in Markdown.

It is even possible to use both MyST and reStructuredText.

https://myst-parser.readthedocs.io/en/latest/using/intro.html#intro-writing

https://docs.appimage.org/packaging-guide/obs.html#working-examples

Most of these are broken. Why?

• https://build.opensuse.org/package/binaries/home:probono/QtQuickApp?repository=AppImage
• https://build.opensuse.org/package/binaries/home:probono/DSRemote?repository=AppImage
• https://build.opensuse.org/package/binaries/home:probono/Qactus?repository=AppImage
• https://build.opensuse.org/package/binaries/home:probono/leafpad?repository=AppImage
• https://github.com/olav-st/screencloud/blob/master/deploy/linux/appimage.yml
• https://build.opensuse.org/package/view_file/home:pbek:QOwnNotes/desktop/appimage.yml?expand=1
• https://build.opensuse.org/package/view_file/home:olav-st:branches:OBS:AppImage:Templates/ScreenCloud/appimage.yml?expand=1
• https://build.opensuse.org/package/view_file/home:pbartfai/LDView/_service:extract_file:appimage.yml?expand=1
• https://build.opensuse.org/package/view_file/home:lachs0r:mandelbulber2/mandelbulber2/appimage.yml?expand=1
• https://build.opensuse.org/package/view_file/home:lachs0r:taisei/taisei/appimage.yml?expand=1

Despite all the greatness of OBS, this is exactly the impression I get: you set stuff up, then wait a year, and then it's not guaranteed to be working anymore... or is it my fault?

It would be nice to have in tab Optional Resources and Features description how to properly pack an appimage with proper theming support.

Add section on how to make AppImages of Qt apps look native on Gtk based on

• probonopd/linuxdeployqt#60 (comment)
• probonopd/linuxdeployqt#60 (comment)

Proposal:

Making AppImages of Qt apps look native on Gtk

Here is an example of a native-looking Qt application running on a Xubuntu (Xfce-based) distribution in an AppImage:

To make AppImages of Qt applications look native on Gtk based systems, you need to bundle plugins/platformthemes/libqgtk2.so and plugins/styles/libqgtk2style.so. Since they do not come with Qt by default anymore, you need to compile them by hand.

Example:

apt-get update
apt-get -y install libgtk2.0-dev
git clone http://code.qt.io/qt/qtstyleplugins.git
cd qtstyleplugins
qmake
make -j$(nproc)
make install 
cd -

(...)

linuxdeployqt (...) -extra-plugins=platformthemes/libqgtk2.so,styles/libqgtk2style.so

At runtime, you need to export QT_QPA_PLATFORMTHEME=gtk2, e.g., by adding this line to a custom AppRun script. (Xubuntu exports this variable automatically).

Background information

According to https://askubuntu.com/a/910143,

The problem has occurred since Qt5.7. In this release, the GTK2 platform theme and style was removed and replaced with the GTK3 platform theme. I've recently been in discussion with the Qt developers and it appears there isn't a GTK3 style to complement the platform theme and there are currently no plans to implement this in the future.

References

• https://askubuntu.com/a/910143
• https://askubuntu.com/a/748186

Maybe we should remove https://github.com/aferrero2707/appimage-testsuite/ from https://github.com/AppImage/docs.appimage.org/blob/master/source/packaging-guide/testing.rst

People misunderstand it:
https://www.reddit.com/r/AppImage/comments/x8gpl5/oldest_version_supported/

Reference:

• aferrero2707/appimage-testsuite#5

We should replace external links with internal ones to descriptions we maintain in the docs, if there are such information. There's a lot of examples with links to projects we describe briefly in other sections of the documentation.

That way, if a link breaks, you just have to fix them once, which makes maintaining a lot easier.

in the documentation there is a longer page that starts very well, but then goes on with "scary" details:

https://docs.appimage.org/user-guide/run-appimages.html

on the main page there is a link to a youtube video with instruction only for the the terminal.

it would be nice to have a single page with first section of the docs on running Appimages plus the videos that can be linked from projects that are using Appimages. (without any reference on how to unpack an appimage file... : - )

It is very important to note that the fuse2 package (provided by the extra repository) is NOT part of the Arch Linux base, nor is it a direct or indirect dependency of any packages in base. On my system, pactree -r fuse2 shows that fuse2 is depended on directly or indirectly by erofs-utils, exfat-utils, ntfs-3g, flatpak, python-llfuse, and libappimage, among a few others. I of course have many packages that optionally have an indirect dependency on fuse2, but it is always sensible to assume that Arch users will not install all the optional dependencies of all their software.

The bottom line is that, curiously, the Arch FUSE problems section of the FAQ states "On Arch Linux, FUSE should work already." This assumption is far LESS likely to be true on Arch, which installs almost absolutely nothing by default, than for basically any other distribution!

The FAQ should really just say
sudo pacman -S fuse2

There seems to be two different sections where hard-coded paths are mentioned. I suggest it might be better to consolidate and merge the information. I'll do this if you'd like, but I need to know how you would like it consolidated.

Maybe move the info from here and merge it onto the reference page. Then add a link to the reference page?
https://docs.appimage.org/packaging-guide/manual.html#no-hard-coded-paths

https://docs.appimage.org/reference/best-practices.html#binaries-must-not-use-compiled-in-absolute-paths

In pkg2appimage there's a dead link to https://docs.appimage.org/packaging-guide/yml-example-file

The following page https://github.com/AppImage/docs.appimage.org/blob/master/source/packaging-guide/advanced/troubleshooting.rst has no links from the rest of the documentation to it.

While looking through the code and the docs. I noticed that the docs do not mention that OWD is also set for type 2 appimage binaries.

CI fails on linkcheck, what does this want to tell me?
I did not even touch any links in my commit.

https://github.com/AppImage/docs.appimage.org/runs/4202987393?check_suite_focus=true

On this page:

https://docs.appimage.org/packaging-guide/optional/appstream.html

the link to:
http://output.jsbin.com/qoqukof

returns internal server error

In the folder packaging-guide/other-resources/, the file discoverability.rst isn't listed in index.rst, therefore it can't be accessed. (Afaik, no other page links to it).

I think it would be good to properly describe what is done during desktop integration process done using AppImageLauncher, and what are differences between it and using simple registering with libappimage (appimage_register_in_system()).

https://docs.appimage.org/reference/desktop-integration.html

I have already asked these questions to @probonopd on AppImage discourse, but I think it would be good to add these answers to docs to make integrating AppImages into stores easier.

I saw two brief hints to update channels in the documentation about AppImage updates

Releases should always update to releases, nightlies always to nightlies, etc. (“channels”)

Whenever` the application encounters issues (e.g., a crash reporter comes up) it could ask the user to check for updates, and accept bug reports only if no newer version is available in the channel

But it didn't find any more information on update channels. I'm currently trying to add an update system supporting channels on an AppImage I'm working on and such information might be usefull. I'm willing to propose a PR with such documentation if I can gather info about it.

As far as my understanding goes, there is no builtin channel support in the AppImage spec or any update tool. The maintainers of an app should upload multiple AppImages on their servers and can choose to "target" the update link on whichever file corresponds to the latest AppImage of the selected channel ? Or is there another way to support update channels I'm not aware of ?

If anyone is aware of a project that already has such a system in place I'm interested in looking into it and to document at least one good use case of such a workflow.

@probonopd silently removed the notice on https://github.com/AppImage/AppImageKit/wiki/FUSE and restored some old, redundant contents. Not entirely sure why. But I guess it's because some information might be missing somewhere?

Anyway, we need better coverage of FUSE and related issues (also Docker etc.) in our docs.