├── .gitignore ├── AppDevelopment.md ├── LICENSE └── README.md /.gitignore: -------------------------------------------------------------------------------- 1 | # Prerequisites 2 | *.d 3 | 4 | # Compiled Object files 5 | *.slo 6 | *.lo 7 | *.o 8 | *.obj 9 | 10 | # Precompiled Headers 11 | *.gch 12 | *.pch 13 | 14 | # Compiled Dynamic libraries 15 | *.so 16 | *.dylib 17 | *.dll 18 | 19 | # Fortran module files 20 | *.mod 21 | *.smod 22 | 23 | # Compiled Static libraries 24 | *.lai 25 | *.la 26 | *.a 27 | *.lib 28 | 29 | # Executables 30 | *.exe 31 | *.out 32 | *.app 33 | -------------------------------------------------------------------------------- /AppDevelopment.md: -------------------------------------------------------------------------------- 1 | # Application development using Flatpak 2 | 3 | This is to describe shortly some aspects regarding packaging of 4 | Flatpak for ARM/i386 required for running Flatpak applications on 5 | Sailfish OS. This is based on 6 | https://github.com/flatpak/flatpak/issues/5 and QEMU instructions. 7 | 8 | For general introduction of application development and packaging 9 | using Flatpak elsewhere. 10 | 11 | 12 | ## Setting up environment 13 | 14 | In the following, we will setup environment for ARM. For i386, you probably don't need to setup QEMU. 15 | 16 | 1. Install QEMU with user static support. For Gentoo, specify 17 | `static-user` use flag of `app-emulation/qemu` and set 18 | ``` 19 | QEMU_SOFTMMU_TARGETS="aarch64 arm i386 x86_64" 20 | QEMU_USER_TARGETS="aarch64 arm i386" 21 | ``` 22 | in make.conf. For Fedora, install `qemu-system-arm qemu-user-static`. 23 | 24 | 2. If configuration is not provided out of the box, as it is for some distributions, add 25 | `/etc/binfmt.d/qemu-arm-static.conf`: 26 | ``` 27 | :qemu-arm:M::\x7fELF\x01\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x28\x00:\xff\xff\xff\xff\xff\xff\xff\x00\x00\x00\x00\x00\x00\x00\x00\x00\xfe\xff\xff\xff:/usr/bin/qemu-arm:F 28 | ``` 29 | For aarch64, add `/etc/binfmt.d/qemu-aarch64-static.conf`: 30 | ``` 31 | :aarch64:M::\x7fELF\x02\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\xb7:\xff\xff\xff\xff\xff\xff\xff\xfc\xff\xff\xff\xff\xff\xff\xff\xff\xfe\xff\xff:/usr/bin/qemu-aarch64:F 32 | ``` 33 | 34 | You may need to register a handler in host machine (don't register a 35 | handler that matches the host machine). See instructions in 36 | https://wiki.gentoo.org/wiki/Embedded_Handbook/General/Compiling_with_qemu_user_chroot . 37 | 38 | 3. Restart systemd-binfmt service: `sudo systemctl restart systemd-binfmt.service` 39 | 40 | 4. Install required platform and SDK: 41 | ``` 42 | flatpak install --user org.kde.Platform/arm/5.12 org.kde.Sdk/arm/5.12 43 | ``` 44 | 45 | 5. Test installation by running 46 | ``` 47 | flatpak run --command=sh --arch=arm org.kde.Platform/arm/5.12 48 | ``` 49 | 50 | If you get into the shell, all works as expected. See below for known issues. 51 | 52 | 53 | ## Compilation and packaging 54 | 55 | Compose JSON or YAML describing the build process. Look for 56 | introduction elsewhere. For examples, see packaging scripts for 57 | [Flathub](https://github.com/flathub) and 58 | [KDE](https://phabricator.kde.org/source/flatpak-kde-applications/). 59 | 60 | For use of locally changed sources, use something like 61 | 62 | ```json 63 | "sources": [ { 64 | "type": "dir", 65 | "path": "../plasma-angelfish", 66 | "skip": [".git", ".flatpak-builder", ".cache"] 67 | } ] 68 | ``` 69 | 70 | for sources. Keep Flatpak packaging script and code in separate folder 71 | or be sure to include `.flatpak-builder` into skipped folders. Note 72 | that the source is relative to JSON path. 73 | 74 | Compile and package the application: 75 | 76 | ``` 77 | flatpak-builder --arch=arm --repo=../flatpak --force-clean ../flatpak-build-desktop org.kde.mobile.angelfish.json 78 | flatpak build-bundle --arch=arm ../flatpak angelfish.flatpak org.kde.mobile.angelfish 79 | ``` 80 | 81 | After that you will find file `angelfish.flatpak` in your current 82 | folder. Transfer that to device and install using 83 | 84 | ``` 85 | flatpak install --user angelfish.flatpak 86 | ``` 87 | 88 | After that, it can be run by 89 | 90 | ``` 91 | flatpak-runner org.kde.mobile.angelfish 92 | ``` 93 | 94 | Assuming that the application has .desktop installed, you can configure its environment using `flatpak-runner`. Just 95 | start the runner from application grid and configure the application environment in it. 96 | 97 | 98 | ## Use of Sailfish keyboard 99 | 100 | Maliit plugin should be mounted by flatpak-runner automatically. No need to adjust the sources. 101 | 102 | 103 | ## Known issues 104 | 105 | When compiling for ARM, there are issues imposed by either absence or broken handling of statx syscall. In practice, 106 | it means that we cannot use `qmake` in the projects compiled against KDE 5.12 Sdk. As is, we are limited to `cmake` on 5.12 right now. Symptoms are errors like "Project ERROR: Unknown module(s) in QT: core dbus" while compiling the projects. 107 | 108 | Corresponding issues are filed and are listed below: 109 | 110 | * https://bugs.kde.org/show_bug.cgi?id=416262 111 | * https://bugs.launchpad.net/qemu/+bug/1861341 112 | * https://invent.kde.org/kde/flatpak-kde-runtime/issues/2 113 | 114 | 115 | On KDE 5.14, `cmake` is possible. However, there are problems with running it using regular x86_64 host (see https://gitlab.com/freedesktop-sdk/freedesktop-sdk/issues/968, probably caused by https://bugs.launchpad.net/qemu/+bug/1805913). As a workaround, I managed to compile when using 116 | 117 | - i686 virtual host 118 | - ext4 fs with 64bit feature disabled (`tune2fs -O ^64bit /dev/sda1`). 119 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2020 Flatpak support for Sailfish OS 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Flatpak support for Sailfish OS 2 | 3 | This is the repository for documentation and for filing issues against current implementation 4 | of Flatpak support for Sailfish OS. 5 | 6 | 7 | ## Status 8 | 9 | Flatpak support requires changes in 10 | [libhybris](https://github.com/libhybris/libhybris/pull/433, merged in 0.0.5.34), support 11 | in kernel (PR_SET_NO_NEW_PRIVS, officially from 3.5), and wrapper program 12 | [Flatpak Runner](https://github.com/sailfishos-flatpak/flatpak-runner). As 13 | a result of these dependencies, the support is device-specific. 14 | 15 | Current issues are listed at 16 | https://github.com/sailfishos-flatpak/main/issues and, for Flatpak 17 | Runner, at https://github.com/sailfishos-flatpak/flatpak-runner/issues 18 | . Notable limitations are due to limited support by Wayland compositor. 19 | In practice, KDE Plasma Mobile applications are 20 | supported best. 21 | 22 | In general, running Flatpak applications and their management is 23 | similar to other Linux platforms. Exception is in use of Flatpak 24 | Runner for executing the applications. This allows to provide 25 | orientation information to the running applications and work around 26 | some limitations of the current Sailfish Lipstick. 27 | 28 | 29 | ## Supported devices 30 | 31 | * Kernel version >= 3.5 (PR_SET_NO_NEW_PRIVS, maybe possible to backport) 32 | * libhybris version >= 0.0.5.34 33 | 34 | 35 | ## Installation and usage 36 | 37 | Assuming that your device has support for Flatpak, you need to enable 38 | repository with the Flatpak packages and install `flatpak` with 39 | `flatpak-runner`: 40 | 41 | ``` 42 | devel-su ssu addrepo rinigus-flatpak http://repo.merproject.org/obs/home:/rinigus:/flatpak/sailfish_latest_armv7hl/ 43 | devel-su pkcon refresh 44 | devel-su pkcon install flatpak-runner 45 | ``` 46 | 47 | Start `flatpak-runner` either from app grid (shown as Flatpak) or from terminal (`flatpak-runner` without root). 48 | This will generate Hybris extension that is used to run applications. Note that the extension 49 | has to be refreshed after libhybris update (usually after Sailfish OS update). This can be done 50 | in `flatpak-runner` under Extension pulley menu action. 51 | 52 | Reboot to finish installation. 53 | 54 | Currently, it is only supported if you install and use Flatpaks from your home folder. This will avoid 55 | filling up system storage and will simplify of application installation. Add Flatpak repositories, 56 | such as Flathub: 57 | 58 | ``` 59 | flatpak remote-add --user --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo 60 | ``` 61 | 62 | For KDE apps: 63 | ``` 64 | flatpak remote-add --user --if-not-exists kdeapps http://distribute.kde.org/kdeapps.flatpakrepo 65 | ``` 66 | 67 | After that, install applications with `flatpak install --user appname` in terminal. It will ask few 68 | questions and install the application with its dependencies. 69 | 70 | For Sailfish OS keyboard support, install 71 | 72 | ``` 73 | flatpak install --user org.kde.PlatformInputContexts.MaliitSailfishOS//5.14 74 | ``` 75 | 76 | Replace with `//5.12` in the end if you wish to use 5.12 KDE runtime. 77 | 78 | 79 | To get applications recognized by Lipstick, run `flatpak-runner`. The runner will also allow you to 80 | set application-specific and default environment variables, Qt scaling and perceived DPI. 81 | 82 | To run applications, either launch them from app grid or run with 83 | 84 | ``` 85 | flatpak-runner org.kde.mobile.angelfish 86 | ``` 87 | 88 | ## App specific tips 89 | 90 | ### Difference between DPI and scale 91 | 92 | As Sailfish devices are HiDPI, there are some times issues with presenting content. By default, Flatpak Runner sets DPI 93 | through Qt environment variable to force the same DPI as on the device. Alternatively, its possible to use scaling, as in 94 | openGL to stretch the output. For Qt apps, usually, there is no big difference on how to approach it as long as DPI times 95 | scale gives the same value. However, there are exceptions and its best to experiment with these settings if the app looks 96 | too big ot too small. In such cases, you could reduce or increase overall scale x dpi to make it feel right. 97 | 98 | DPI and scaling can be changed in Flapak Runner, either globally or for specific app. 99 | 100 | ### QtWebengine and related applications: Angelfish 101 | 102 | It seems that QtWebengine (Qt 5.14) overshoots at high DPI values wih the scaling. So, I suggest to increase 103 | scaling and reduce DPI. On my device with ~430DPI, I am using 3x scaling and 120 DPI. This results in 104 | 360DPI/430DPI reduction in overall size which is my preference in this case. 105 | 106 | Angelfish allows to setup your navigation bar buttons in Settings. While the default is based on KDE 107 | requirements, its easy to make it into the bar that we are used to. In my case, I have: tabs, back, address, 108 | and reload buttons. Menu buttons are hidden. 109 | 110 | To get into the main and context menus (left and right menus by default), all you have to do is to 111 | slide your finger along bottom border of the screen. Depending on direction, you will get either main or 112 | context menu. As, at least in my case, menus were mainly used to access back and reload buttons, I don't 113 | have much use for them if the buttons are out. Note that the menu buttons will appear in landscape mode 114 | as there is more screen space over there. 115 | 116 | Consider also using `Reduce window when keyboard is shown` to scale app window when the keyboard is shown. Its useful 117 | when input entries are shown under the keyboard. For example, find in page entry. 118 | 119 | ### Mirage 120 | 121 | Similar to Angelfish, scale 3x and DPI 130 is used. It maybe due to older Qt that is used (5.12 for flatpaks at the 122 | moment of writing). 123 | 124 | Its recommended to use `Reduce window when keyboard is shown` to be able to see your message while you type it. 125 | 126 | ### Telegram Desktop 127 | 128 | To make org.telegram.dekstop working add following environment variable: `QT_QPA_PLATFORM=wayland`. To set, 129 | in `flatpak-runner`, add new variable and specify its name as `QT_QPA_PLATFORM` and value as `wayland`. 130 | 131 | ## Application development 132 | 133 | For description of application development, see separate 134 | [HOWTO](AppDevelopment.md). 135 | --------------------------------------------------------------------------------