Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add a flatpak manifest #610

Merged
merged 2 commits into from
Aug 7, 2020
Merged

Add a flatpak manifest #610

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1c43043
Add flatpak manifest and related documentation
Jul 6, 2020
2a8c5af
Add flatpak GH action
Jul 6, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 39 additions & 0 deletions .github/workflows/testing.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
75 changes: 74 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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...]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would there be any easy way to make this shorter? Maybe flatpack can automically put a symlink in ~/bin or /usr/local/bin? Or otherwise register a short name so you can at least use flatpack run hamster (i.e. using the same base command as a normal install)?

Also, it might be good to clarify that (IIUC) the flatpack-hamster will be autostarted through dbus (e.g. when the shell extension tries to access it). That does make me wonder: What does flatpack do when the dbus name is already registered (i.e. when hamster is normally installed as well)? From a quick test it seems to (silently) not claim the name, that is, when I start the flatpack, the flatpack GUI connects to the non-flatpack dbus service, and when I kill the non-flatpack services, it still spawns the non-flatpack ones, rather than the flatpack ones.

For most users, I guess this is not so much an issue (they would typically only install the flatpack version), but it would be at least to document these caveats somewhat. Also, one usecase I see for flatpack is that it would help with testing nightly builds or pullrequests, and then it would be convenient of someone could install the flatpack version next to the regular version and have them completely isolated.

Copy link
Contributor

@mwilck mwilck Aug 7, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That does make me wonder: What does flatpack do when the dbus name is already registered (i.e. when hamster is normally installed as well)? From a quick test it seems to (silently) not claim the name, that is, when I start the flatpack, the flatpack GUI connects to the non-flatpack dbus service, and when I kill the non-flatpack services, it still spawns the non-flatpack ones, rather than the flatpack ones.

I don't think it's possible to hijack a well-known dbus address. I guess it shouldn't be. At best, hamster itself should log a meaningful message when it fails to acquire the address. But that's independent of packaging. It applies also to a situation with installed hamster and local (developer) instance, for example.

It's a general problem that I have with all applications that can be installed either "regularly" or as flatpak/snap/appimage (you name it): It's highly intransparent to the user which package she is activating. DBus makes it even more intransparent, of course.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think it's possible to hijack a well-known dbus address. I guess it shouldn't be. At best, hamster itself should log a meaningful message when it fails to acquire the address. But that's independent of packaging. It applies also to a situation with installed hamster and local (developer) instance, for example.

Well, there's two parts to this: One is the claiming of a dbus name at runtime, which is something hamster should report. The other, which I was thinking of, is installing a file in /usr/share/somewhere that declares that a dbus interface exists and what binary to autostart if the name is requested but not on the bus yet (at least that's how I gather it works). This is something that flatpack install should handle, but maybe flatpack handles this differently? Also, it seems that the dbus name should match the flatpak name, not sure if our WindowServer postfix is then supported (the primary service does match).

```

### Install from sources

#### Dependencies
Expand Down Expand Up @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This suggests it just builds the flatpack, but I think it also installs it. Might be good to clarify.

[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

Expand All @@ -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)
Expand Down Expand Up @@ -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/
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why use gio copy here? Looks like these are two regular paths that can just use normal cp?

```

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
Expand Down
68 changes: 68 additions & 0 deletions org.gnome.Hamster.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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"
]
}