search

AppImage / docs.appimage.org

Source code of AppImage project's documentation
https://docs.appimage.org/
Other
43 stars 42 forks source link

Decision tree and where to download the tools #30

Open probonopd opened 5 years ago

probonopd commented 5 years ago

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:

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

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).

probonopd commented 5 years ago

Maybe we should also add a decision tree

And then point to the tools needed depending on the answers to those questions.

freakboy3742 commented 5 years ago

When I say "toolchain" I mean pkg2appimage, appimagetool, and/or any other tool that is needed to turn an AppDir into an AppImage.

Saying "The tools are from third parties" is one of things that is technically correct, but functionally unhelpful as an observation. The AppImage documentation (docs.appimage.org) directly references these tools, suggests that they should be used, and provides detailed documentation on their use. They're hosted as part of the AppImage Github org. But not once do the docs include the phrase "and here's how to install them".

And if the answer is "you don't; you download the AppImage and run it", that's fine - but you need to say that.

Talking about a decision tree for all these options is great - but you're missing step 0. Assuming I have a clean Ubuntu install - how do I get anything going?

probonopd commented 5 years ago

Thanks for your feedback, which I honestly appreciate and which is extremely helpful. I know that our developer tools are complex and might look a bit frightening at first sight, but we really try to be helpful to anyone who wants to package an application in AppImage format.

Sometimes it's not easy to know what someone seeing the project for the very first time finds hard. But now that you are saying it, I agree!

Assuming I have a clean Ubuntu install - how do I get anything going?

Actually my recommendation is never to do builds on a local developer machine but on services like the Open Build Service, Travis CI or GitLab CI for a) reproducability and b) supportability (by us), but I guess that is a matter of preference.

probonopd commented 5 years ago

First draft of the decision tree, might still contain errors. Asking for review by @TheAssassin

View here

Editor

graph TD
C{Are you the author of the application?}
C -->|Yes|A
C -->|No| D[Ask the author to provide an AppImage]
D --> DD[Will the author provide an AppImage?]
DD -->|Yes| F[The AppImage team will support the application author]
DD -->|No| G[Do you want to make a quick and dirty one for your own use?]
G --> |No| E
G --> |Yes| GG[Do you have the source code?]
GG --> |No | GGG[Do you have a deb?]
GG --> |Yes| A
GGG --> |No | manual
GGG --> |Yes| pkg2appimage

A[Is the application Electron-based?]
A --> |Yes| electron-builder
A --> |No| AA

AA[Is the application Qt/QML-based?]
AA --> |Yes| qt
AA --> |No| AAA

AAA[Is the application Python code?]
AAA --> |Yes| python
AAA --> |No| AAAA

AAAA[Is the application compiled C/C++/... code?]
AAAA --> |Yes| qt
AAAA --> |No| manual

E[End]
pkg2appimage[Use pkg2appimage]
manual[Use manual scripting and appimagetool]
electron-builder[Use electron-builder]

qt[Do you want something automagic or something configurable with plugins?]
qt --> |Simple| linuxdeployqt
qt --> |Configurable| linuxdeploy
linuxdeployqt[Use linuxdeployqt]
linuxdeploy[Use linuxdeploy]

python[Do you want to use Conda?]
python --> |Yes| condaplugin
python --> |No| pkg2appimage

condaplugin[Use linuxdeploy-plugin-conda]
freakboy3742 commented 5 years ago

So... I feel like I'm missing something here... because while I gather the decision tree is something you' are enthusiastic about, it does nothing to address the concern I raised.

I didn't have any particular difficulty navigating the content on the current docs site to determine the options that seemed appropriate.

I did, however, have difficulty working out how to obtain the command line tools that were referenced by the docs. As an end user, It does me absolutely no good to have a first class funnel getting me to a page that tells me I need to use "pkg2appimage" if there are no instructions on how to obtain pkg2appimage.

TheAssassin commented 5 years ago

A chance to rant back? Yay!

The big issue there is that we have a certain and working set of tools but some people refuse to let the old ones go. There's plenty ones that have huge issues and shouldn't be used by anyone, but are required to be documented by those people. pkg2appimage for instance is quite insecure and there's known attacks on it; also it creates bloaty packages and is advertised to work e.g., for Python, which clearly is wrong. Therefore this thing shouldn't even be mentioned, and sent to retirement. Just like many other things still mentioned there.

I don't consider linuxdeploy difficult (it's a lot easier than things like linuxdeployqt, especially since it has some meaningful logging...), and it's not hard to find in general, and also not on the docs. ePretty simple IMO: you want to package something native? Check out https://docs.appimage.org/packaging-guide/from-source/native-binaries.html. There's a link to linuxdeploy in the intro already:

The AppImage team provides tools that simplify the packaging process significantly. These tools are semi-automatic, and ship with various features needed to bundle said shared library dependencies correctly. The one we are going to use in this guide is linuxdeploy.

All the examples showing how to use it involve this "installation" step, e.g., https://docs.appimage.org/packaging-guide/from-source/native-binaries.html#bundling-resources-into-the-appdir, https://docs.appimage.org/packaging-guide/from-source/native-binaries.html#using-qmake-and-make-install.

Then we have the software overview, which lists all the tools and links to them: https://docs.appimage.org/introduction/software-overview.html#linuxdeploy

I can't take this "criticism" or "feedback" all that seriously. If there had been any interest in improving the docs, it'd been easy enough to come here first and open issues, without having to use caps. I have serious doubts @freakboy3742 really read more deeply into the docs or even used the search.

Reading @freakboy3742's last comment, all that is missing seems mentioning all our tools are shipped as AppImages in the software overview page and maybe post direct links to the GitHub release pages or something.

Regarding a "decision tree", there's already an Overview that should point people in the right direction. PRs welcome, this thing might need some improvements.

@freakboy3742, I don't have the same point of view on the docs that you might have, if you ever wrote docs you'll know that. Please consider contributing to our docs to improve them and avoid random, off-putting Twitter rants. We can reply to any question asked in a GitHub issue, or also on IRC. But I'm not reacting to Twitter stuff, I don't like proprietary (anti-)social media platforms and certainly won't register there. And I can't take this serious anyway. As said, if you want something to change, not just complain about it, be our guest, I know the docs aren't top notch.

probonopd commented 5 years ago

As an end user, It does me absolutely no good to have a first class funnel getting me to a page that tells me I need to use "pkg2appimage" if there are no instructions on how to obtain pkg2appimage.

Yes, I get it. At the end of the decision tree there should be a link to the appropriate place. I just did not have the time to do it yet.

probonopd commented 5 years ago

The big issue there is that we have a certain and working set of tools but some people refuse to let the old ones go.

Me :-)

(pkg2appimage) ... shouldn't even be mentioned, and sent to retirement

I wrote above:

pkg2appimage (a script for converting existing deb packages to AppImage; "last resort" if you can't use one of the tools above

is advertised to work e.g., for Python, which clearly is wrong

Err, what? E.g., https://github.com/AppImage/pkg2appimage/blob/9249a99e653272416c8ee8f42cecdde12573ba3e/recipes/Mu.yml

I can't take this "criticism" or "feedback" all that seriously.

Well, I do. In fact, I sincerely thank @freakboy3742 because he is pointing out what is making AppImage "difficult" for application developers; and I'd like to improve. Because AppImage exists to remove complexity. First and foremost for the end user, but then also for the application developer.

I know the docs aren't top notch.

They are much better now than they ever were before especially thanks to your hard work, but they can (and should) be improved, especially with "easy fixes" like telling where to download the tools we are describing. And maybe a decision tree ;-)

freakboy3742 commented 5 years ago

@TheAssassin

I don't have the same point of view on the docs that you might have, if you ever wrote docs you'll know that. Please consider contributing to our docs to improve them and avoid random, off-putting Twitter rants

I know having someone dump on your work isn't motivating; and for that, I apologize. My Twitter rant was intended as just that - a rant. I very specifically didn't tag the project, or anyone involved in the project, in that rant. @probonopd sought me out, not the other way around. My original posts came from a place of extreme frustration at failing to even get a "hello world" example going, and I lashed out.

I would gladly contribute to the docs. However, at this point, I've done everything I've been able to do. Other than reporting that the problem exists, I'm literally not in a position to help, because I haven't been able to get anything working yet. I am stuck at step 0: how do I install the software.

Also: "If you ever wrote docs"... You might want to do a little reading about my history in FLOSS. This isn't my first open source rodeo.

freakboy3742 commented 5 years ago

@probonopd

is advertised to work e.g., for Python, which clearly is wrong

Err, what? E.g., https://github.com/AppImage/pkg2appimage/blob/9249a99e653272416c8ee8f42cecdde12573ba3e/recipes/Mu.yml

Yes. I found that example. And it didn't work. Or, at least, I couldn't get it to work.

I eventually worked out that pkg2appimage was just a shell script, so I cloned the repository and ran it directly from there; however, the script tries to move an icon image to /usr/share location where it tries to move the image doesn't exist.

probonopd commented 5 years ago

@probonopd sought me out, not the other way around.

Yes. Because you voiced something I deeply care about - making things easy to use.

I haven't been able to get anything working yet. I am stuck at step 0: how do I install the software.

Is that still an issue now? I linked the download pages of the various parts above, and to close this ticket, will also link them in the documentation.

You don't install AppImages, nor do you install bash scripts. But I think you already figured that part out ;-)

probonopd commented 5 years ago

On that note, @TheAssassin is there a global "search and replace" like functionality to define in rst that whenever the world "linuxdeploy" appears it automatically gets linked there?

freakboy3742 commented 5 years ago

@probonopd I have more of an idea what is going on; I haven't had a chance to actually try any of this advice to see if I can generate a working AppImage. My comments were intended the "If I were to just read the documentation" sense.

probonopd commented 5 years ago

If you point us to the project you are trying to package we'll try to help you :)

Btw, getting AppImage as an output format into https://beeware.org/ would be aweseome, and certainly something I'd like to help with.

freakboy3742 commented 5 years ago

The initial target app is Toga's Tutorial 0.

The end goal will be to template the solution so it can be used by Briefcase as a mechanism for turning an Python project into a native app package for any Python app.

probonopd commented 5 years ago

@TheAssassin do you know why https://github.com/AppImage/docs.appimage.org/commit/823992ffde2112f87f3ad2184b722c4ad2d09ad7 failed? Old-fashioned .md editing never "failed" me ;)

TheAssassin commented 5 years ago

Old-fashioned .md editing never "failed" me ;)

That's just not true at all. We're running a link check on Travis, there's broken links somewhere. Format doesn't make a difference.

Also, you may send your changes as a PR. Then we can double-check your changes. After all, you're a rookie, and that way errors can be prevented.

probonopd commented 5 years ago

Yes. Can you see what I did wrong?

probonopd commented 5 years ago

Yes. I found that example. And it didn't work. Or, at least, I couldn't get it to work.

Just checked, works for me... this is Mu AppImage created by it:

mu

TheAssassin commented 5 years ago

Either of you is hereby invited to write whatever you think that decision tree should contain. Preferrably in reStructured Text, but if you are lazy and refuse to learn two or three things, please write them in Markdown. Otherwise I tend to closing this issue, if we're not going to work on it anyway. I am not entirely sure what a decision tree like this should contain, so I don't want to invest time if the outcome is unsure.

probonopd commented 5 years ago

Either of you is hereby invited to write whatever you think that decision tree should contain.

https://github.com/AppImage/docs.appimage.org/issues/30#issuecomment-521536237

Asking for review by @TheAssassin

I am not entirely sure what a decision tree like this should contain

tree

TheAssassin commented 5 years ago

There's many errors in this tree... Please revisit.

probonopd commented 5 years ago

Possibly. I did it in a hurry and while traveling. Could you be a little bit more specific though?