Merge pull request #610 from tchernobog/features/flatpak-manifest

Add a flatpak manifest

Author: matthijskooijman

.github/workflows/testing.yml

@@ -77,3 +77,42 @@ jobs:
       - name: Run flake8
         run: |
           flake8 --count --show-source --statistics
+
+  flatpak:
+    # This job builds Hamster for flatpak, and runs its tests
+    # inside the sandbox.
+    name: Test the flatpak build
+    runs-on: ubuntu-20.04
+    steps:
+      - name: Prepare repo
+        uses: actions/checkout@v2
+      - name: Install system packages
+        # It would be good to cache the GNOME Sdk, as it
+        # is rather big to download each time.
+        env:
+          DEBIAN_FRONTEND: noninteractive
+        run: |
+          PACKAGES="flatpak flatpak-builder dbus-x11"
+
+          sudo apt-get update
+          sudo apt-get install -yq ${PACKAGES}
+      - name: Install GNOME SDK for flatpak
+        run: |
+          flatpak remote-add --user --if-not-exists --from flathub https://flathub.org/repo/flathub.flatpakrepo
+          flatpak install --user -y flathub org.gnome.Platform//3.36 org.gnome.Sdk//3.36
+      - name: Build application
+        run: |
+          flatpak-builder --repo=build/flatpak/repo build/flatpak/tmp org.gnome.Hamster.json
+      - name: Run tests inside sandbox
+        run: |
+          dbus-launch flatpak-builder --run build/flatpak/tmp org.gnome.Hamster.json python3 -m unittest
+      - name: Export bundle and try to install it
+        run: |
+          mkdir -p dist
+          flatpak build-bundle --runtime-repo=https://flathub.org/repo/flathub.flatpakrepo build/flatpak/repo dist/Hamster.flatpak org.gnome.Hamster
+          flatpak --user -y install dist/Hamster.flatpak
+      - name: Upload built artifact
+        uses: actions/upload-artifact@v2
+        with:
+          name: Flatpak application
+          path: dist/Hamster.flatpak

README.md

@@ -58,6 +58,33 @@ Installation:
 Easy installation on any distribution supporting snap:  
 https://snapcraft.io/hamster-snap
 
+##### Flatpak
+
+[Flatpak](https://flatpak.org/) enables you to install Hamster in a versioned
+environment and then run it inside a sandbox. It is a method independent from
+your distribution-specific packaging system, ensuring that the application can
+always be reproducibly built, even without hunting down all of the dependencies
+yourself. Debugging is made easier as every user has the exact same environment
+at runtime. Permissions are limited to what the application really needs to
+function properly.
+
+If you downloaded the file with the Hamster bundle (ending in ``.flatpak``), you
+can directly install it with:
+
+```bash
+flatpak install --reinstall Hamster.flatpak
+```
+
+If you would like to install Hamster only for your user, please pass the
+``--user`` option to the above command.
+
+After installation, if you need to invoke Hamster from the command line,
+you can do so with:
+
+```bash
+flatpak run org.gnome.Hamster [args...]
+```
+
 ### Install from sources
 
 #### Dependencies
@@ -125,6 +152,20 @@ as discussed [here](https://github.com/projecthamster/hamster/pull/421#issuecomm
 
 Now restart your panels/docks and you should be able to add Hamster!
 
+##### Flatpak
+
+Alternatively, you can also build a sandboxed
+[flatpak](https://www.flatpak.org/) yourself. You might need to install the
+GNOME SDK beforehand (an error will notify you about it, if needed). Execute:
+
+```bash
+flatpak-builder --force-clean --user --install \
+    build/flatpak org.gnome.Hamster.json
+```
+
+This creates a temporary flatpack build folder in the ``build/flatpak``
+directory. Once the app is installed, the whole ``build/flatpack/`` directory
+can be removed.
 
 #### Uninstall
 
@@ -135,6 +176,14 @@ sudo ./waf uninstall
 Afterwards `find /usr -iname hamster` should only list unrelated files (if any).
 Otherwise, please see the [wiki section](https://github.com/projecthamster/hamster/wiki/Tips-and-Tricks#uninstall)
 
+##### Flatpak
+
+To remove the installed flatpak, just run:
+
+```bash
+flatpak uninstall org.gnome.Hamster
+```
+
 #### Troubleshooting
 
 [wiki section](https://github.com/projecthamster/hamster/wiki/Tips-and-Tricks#troubleshooting)
@@ -178,7 +227,31 @@ run:
     python3 -m unittest tests.test_stuff.TestFactParsing
     python3 -m unittest tests.test_stuff.TestFactParsing.test_plain_name
 
-#### Migrating from hamster-applet
+##### Flatpak
+
+To run the tests inside the flatpak, use:
+
+```bash
+flatpak-builder --run build/flatpak org.gnome.Hamster.json \
+    python3 -m unittest
+```
+
+#### Migrating
+
+##### Migrating data to flatpak
+
+If you would like to retain your data from a non-flatpak installation,
+you can do so by running:
+
+```bash
+gio copy -b \
+    ~/.local/share/hamster/hamster.db \
+    ~/.var/app/org.gnome.Hamster/data/hamster/
+```
+
+After checking everything works, you can remove the original database.
+
+##### Migrating from hamster-applet
 
 Previously Hamster was installed everywhere under `hamster-applet`. As
 the applet is long gone, the paths and file names have changed to

org.gnome.Hamster.json

@@ -0,0 +1,68 @@
+{
+    "app-id": "org.gnome.Hamster",
+    "runtime": "org.gnome.Platform",
+    "runtime-version": "3.36",
+    "sdk": "org.gnome.Sdk",
+    "command": "hamster",
+    "modules": [
+        {
+            "name": "intltool",
+            "sources": [
+                {
+                    "type": "archive",
+                    "url": "https://launchpad.net/intltool/trunk/0.51.0/+download/intltool-0.51.0.tar.gz",
+                    "md5": "12e517cac2b57a0121cda351570f1e63"
+                }
+            ],
+            "cleanup": [ "*" ]
+        },
+        {
+            "name": "python3-hamster-dependencies",
+            "buildsystem": "simple",
+            "ensure-writable": [
+                "easy-install.pth",
+                "setuptools.pth"
+            ],
+            "build-commands": [
+                  "pip3 install --no-index --find-links=\"file://${PWD}\" --prefix=${FLATPAK_DEST} dbus-python pyxdg"
+            ],
+            "sources": [
+                {
+                    "type": "file",
+                    "url": "https://files.pythonhosted.org/packages/62/7e/d4fb56a1695fa65da0c8d3071855fa5408447b913c58c01933c2f81a269a/dbus-python-1.2.16.tar.gz",
+                    "sha256": "11238f1d86c995d8aed2e22f04a1e3779f0d70e587caffeab4857f3c662ed5a4"
+                },
+                {
+                    "type": "file",
+                    "url": "https://files.pythonhosted.org/packages/39/03/12eb9062f43adb94e30f366743cb5c83fd15fef026500cd4de42c7c12280/pyxdg-0.26-py2.py3-none-any.whl",
+                    "sha256": "1948ff8e2db02156c0cccd2529b43c0cff56ebaa71f5f021bbd755bc1419190e"
+                }
+            ]
+        },
+        {
+            "name": "hamster",
+            "buildsystem": "simple",
+            "builddir": true,
+            "prefix": "/app",
+            "build-commands": [
+                "./waf configure --prefix=${FLATPAK_DEST}",
+                "./waf build",
+                "./waf install"
+            ],
+            "sources": [
+                {
+                        "type": "dir",
+                        "path": "."
+                }
+            ]
+        }
+    ],
+    "finish-args": [
+        "--socket=wayland",
+        "--socket=fallback-x11",
+        "--filesystem=xdg-documents",
+        "--own-name=org.gnome.Hamster",
+        "--own-name=org.gnome.Hamster.GUI",
+        "--own-name=org.gnome.Hamster.WindowServer"
+    ]
+}