Begin documentation with a simple copy&paste example

[probonopd]

https://github.com/ok2cqr/cqrlog/issues/110#issuecomment-416686307

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.

[TheAssassin]

The new documentation is very structured, and guides one to simple guides. There is no need for random copy-paste stuff, which leads to people not understanding, producing broken results.

The problem the author of that issue had is that you linked him to >1 page containing information, with too many copy-paste example things, without any real structure. Compared to the packaging guide I am writing at the moment, that's a pure mess.

[probonopd]

He write:

No way without reading MB of documentation and manuals"

For being practical, let's say 1 page A4 is the maximum he is willing to read. So would I (in his position). More than that and it's perceived "too complicated". Especially having to read a whole "packaging guide" just to do anything is perceived as "way too complicated".

[TheAssassin]

You don't have to read a "whole packaging guide", that's my point.

If you look at https://docs.appimage.org, you'll quickly find "Packaging guide" with its "Overview". Inside the "overview", you can find the options for packaging. If you decide to go for "packaging from source", you quickly jump to the "native binaries" dialog, which guides you through packaging very quickly. That's far from complex. And a lot more straightforward than having 20k copy-paste examples, where you must find one that suits you which you don't understand but copy paste and then waste hours of changing until it works, without understanding a single line of it.

And if someone is not willing to understand technologies they're using, they should rethink why they're developing software.

[probonopd]

And if someone is not willing to understand technologies they're using, they should rethink why they're developing software.

I disagree. Many people are developing software who have not the slightest clue on how the Kernel works. I would say the majority of application developers actually.

[TheAssassin]

Applying this issue to the docs is just not fair. Reading the issue from the beginning, the problem is that there were tons of different documents in tons of locations. I bet you that they'd like docs.appimage.org. But why are we even talking about the author, instead of inviting them to the discussion?

[probonopd]

Indeed. @ok2cqr we'd appreciate to hear your thoughts on this.

[ok2cqr]

I'm full time developer who works on commercial project. I wanted to have AppImage for my personal project I develop in my spare time. Yes, the truth is, I'm not so keen in Kernel or other low level things. The application is developed in FreePascal/Lazarus, uses MySQL database and other tools, the screenshot is here: https://cqrlog.com/images/users/ok2cqr.png

I'd like to have simple step by step how to create the first app image. My application has a lot of dependencies (mysql, libhamlib, xplanet), but the fist step would be just simple AppImage build, dependencies will be added later. The documentation on GitHub seems to be chaotic for me. A lot of information about details but no step by step manual for AppImage build by hand. I will study it in more details but I'd like to have working AppImage, first.

Thanks for link to the https://docs.appimage.org/packaging-guide/manual.html. I didn't know it exists. I looked to github and didn't find anything so clear like the link above.

[TheAssassin]

@ok2cqr in fact we don't require anybody to learn how AppImage works in detail. I think you could also try to use linuxdeploy to bundle your dependencies, which will copy in all shared library dependencies.

Please beware our docs are still largely copy-pasted from our wiki. Feedback welcome, improvements even more.

Please feel free to visit us on IRC, where we can help you interactively.

[probonopd]

I am helping @ok2cqr on making an AppImage for his tool, but I think this projects can learn from the struggles of a new user with our current documentation, which @TheAssassin is currently working on.

[onpon4]

I'm going to have to firmly, resoundingly concur that the documentation should be doing this. I've tried to learn how to make an AppImage several times over the last couple of years and the documentation is completely inaccessible. It feels like I'm banging my head against a brick wall. I see the documentation talking over and over again about the benefits of AppImage and how there's a million different ways to build an AppImage… I can't work with that. Maybe it's ADHD, I don't know, but either way I can't work with this and every time I try all I get for my efforts is losing all of my spoons. I need a simple starting point with how to make a basic AppImage, a Hello World example.

🕵️

[probonopd]

What language is your application written in @onpon4?

Depending on this, you can use the most appropriate tool.

[onpon4]

One is in C, most are in Python.

🕵️

[probonopd]

For C, assuming you are using cmake, one option is to use go-appimage:

# Build your C application and 'install' it to an AppDir
cmake . -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr
make -j$(nproc)
make DESTDIR=appdir -j$(nproc) install ; find appdir/

# Make sure you have appdir/usr/share/applications/*.desktop
# If not, create it and make sure it passes desktop-file-validate

# Finalize the AppDir and turn it into an AppImage
wget -c https://github.com/$(wget -q https://github.com/probonopd/go-appimage/releases -O - | grep "appimagetool-.*-x86_64.AppImage" | head -n 1 | cut -d '"' -f 2)
chmod +x appimagetool-*.AppImage
./appimagetool-*.AppImage deploy appdir/usr/share/applications/*.desktop # Bundle everything except what comes with the base system
# and
VERSION=1.0 ./appimagetool-*.AppImage ./Some.AppDir # turn AppDir into AppImage

For Python please see https://github.com/niess/python-appimage#for-applications-developers.

[onpon4]

I'm not using cmake for anything, no. In any case I'm not going to make a new release of the C game for some time so I don't really want to spend spoons on that right now. As for python-appimage, I don't see any documentation for it either within or linked by the repo, just installation instructions.

🕵️