Add guides for common types of apps

[allanday]

Since flatpak usage varies according to the type of app someone is building, we ought to ensure that there is documentation for the most common app types. The documentation plan suggests the following:

• [x] Python
• [x] Electron
• [ ] Vala
• [ ] Java (see #17)
• [ ] Ruby/gems

For each of these, we probably want:

• Guidance on how each one differs from the standard build methods
• Explain how to use any special tools
• Flag any quirks
• Point to examples

[TingPing]

Some simple examples:

        {
            "name": "quaternion",
            "buildsystem": "cmake-ninja",
            "builddir": true,
            "config-opts": [
              "-DCMAKE_BUILD_TYPE=Release"
            ],
            "sources": [
                {
                    "type": "git",
                    "url": "git://github.com/QMatrixClient/Quaternion.git",
                    "branch": "v0.0.5",
                    "commit": "f6ae506c14acb223bdc196124efd4f35d6ffa2bb"
                }
            ]
        }

Note that cmake-ninja is simply a faster variant of cmake when it works (usually)

   {
      "name": "hexchat",
      "buildsystem": "meson",
      "config-opts": [
        "--buildtype=release"
      ],
      "sources": [
        {
          "type": "archive",
          "url": "https://dl.hexchat.net/hexchat/hexchat-2.14.1.tar.xz",
          "sha256": "b032e4bcebe2229f87047439979a1246ddcbf599e7e538baa3f2abfac9a003a2"
        }
      ]
    }

[cpba]

I've been looking for an application to serve as a basis for the python tutorial, but the issue I have realised is that if the app already uses a buildsystem such as meson, building it is no different than any other c/c++ app.

What's different is building python dependencies, these usually must be built using the simple buildsystem and they often have other dependencies of their own, meriting the use of flatpak-pip-generator.

Should we have a tutorial on how to build python modules and how to use flatpak-pip-generator rather than a tutorial on a whole python app?

[TingPing]

@cpba Yes showing python dependencies would be very helpful.

[cpba]

@allanday Would something along these lines be acceptable?

https://gist.github.com/cpba/9ec5e95b1f91950aa931d7a62d35f43d

I'm not completely sure about some of the claims I make, it would benefit from some fact checking.

[allanday]

This looks great @cpba ! I've created a structure to drop language-specific guides into, including an empty page for the Python guide. Do you want to push your work there?

[cpba]

@allanday I do. I've made some changes following the suggestions in the gist and sent a pull request.

[allanday]

@allanday I do. I've made some changes following the suggestions in the gist and sent a pull request.

Thanks, I've merged this into the guides branch and made some changes. I hope these are OK. Thanks again, and don't hesitate to propose changes of your own.

I'll maybe wait until we have another guide in place before doing a PR for the branch.

[cpba]

@allanday I cleaned up my electron tutorial a bit: https://github.com/cpba/flatpak-manifests/blob/master/doc-drafts/electron-tutorial.md

If you think it's something that would work as a guide I'll try to fix it up a bit more and send a pull request.

[allanday]

@allanday I cleaned up my electron tutorial a bit: https://github.com/cpba/flatpak-manifests/blob/master/doc-drafts/electron-tutorial.md

This looks excellent, @cpba ! There are some style changes I'd like to make, but the content is really great.

It would be good to host the example app somewhere more official, perhaps under flatpak.

[cpba]

It would be good to host the example app somewhere more official, perhaps under flatpak.

@allanday I've made a barebones electron app with some flatpak branding to use with the tutorial:

https://github.com/cpba/electrondemo

Can you create a repo for me so that I can import it? I'm not in the flatpak group.

[allanday]

I've merged @cpba's electron tutorial into the guides branch. There were some questions about whether the technical recommendations are correct on IRC and it would be good to have that confirmed one way or another.

[cpba]

I'm still a bit uneasy about the electron guide.

It could scare off electron devs and make them dismiss flatpak as being unnecessarily complex, more so if their build system already offers them automatic deb, rpm, appimage and snapd support.

Do you think it would be a good idea to point them to electron-forge? It might be more palatable for people used to nodejs workflows.

[TingPing]

@cpba The problem is if we want these apps on Flathub they have to have a strict build system anyway.

[cpba]

I agree, it's why I wrote the guide using flatpak-builder.

But I'm thinking promoting flapak itself may be more important than promoting flathub. From the point of view of an electron dev flatpak seems to create more problems than it solves. rpm/deb/appimage/snapd look like better options when viewed through that narrow lens.

Maybe there could be a line like "if this looks too complicated and you just want to create a package for your website use this. Understand that it has so and so limitations"

[TingPing]

I think it would be fine to show both paths. The bundles can still be imported into a repo which should be shown (nobody should host just bundles).

[cpba]

I didn't manage to build the electron sample app using electron-forge, I've opened an issue.

This may very well just be me doing something wrong, but I can't write anything useful about it if I can't get it to work first.

In the mean time it may be best to avoid mentioning this method, unless somebody else has better luck with it.

[cpba]

Update on this, the electron-forge method does work and is very straightforward, a properly configured electron-forge project can be built as a single file flatpak bundle with a single command, and then imported into a repository with another. (although it still wouldn't be suitable for publishing on flathub)

However, the catch is that it requires fdo sdk 1.4 for it to work, which is unsupported and unavailable from flathub.

There's an issue open about this:

https://github.com/endlessm/electron-installer-flatpak/issues/17

[allanday]

Should we land the guides branch as is, or wait for wait for electron-forge support?

[cpba]

I think we should land it as is.

[allanday]

Merged! Thanks for your help, @cpba.

Now the race is on to add some more guides. :smile:

[subins2000]

@allanday Please add Ruby/gem to the list too. Found this README file to be extremely useful while including a gem dependency : https://github.com/flatpak/flatpak-builder-tools/tree/master/rubygems