Difference between revisions of "Flatpak"

From GnuCash
Jump to: navigation, search
(→‎Known Issues: current list)
(Use templates: URL:Bugs, URL:FH, URL:FP, URL:FP-docs, URL:GH, URL:wp)
 
(64 intermediate revisions by 7 users not shown)
Line 1: Line 1:
 +
[[Category:Flatpak|en]]
 
{| class="wikitable" style="margin: auto;"
 
{| class="wikitable" style="margin: auto;"
 
! scope="row"|Languages
 
! scope="row"|Languages
 
| [[de/{{PAGENAME}}|Deutsch]]
 
| [[de/{{PAGENAME}}|Deutsch]]
 
|}
 
|}
−
[https://flatpak.org/ Flatpaks] are bundles which besides the program also contain all required libraries. Use cases:
+
[{{URL:FP}} Flatpaks] are bundles which besides the program also contain all required libraries. Use cases:
 
:*If your Linux distribution is ''too old'' to offer all required libraries but has Flatpak support, you can install a ''recent released'' version of GnuCash from the '''FlatHub''' repository.
 
:*If your Linux distribution is ''too old'' to offer all required libraries but has Flatpak support, you can install a ''recent released'' version of GnuCash from the '''FlatHub''' repository.
−
:*If a developer asks you to ''test'' a patch, you can use a ''nightly'' version from '''our Flatpak repository'''.
+
:*If a developer or a translator asks you to ''test'' their recent work, you can use a ''nightly'' version from '''our Flatpak repository'''.
 +
Note flatpak's '''Sandbox''' concept: it uses files in
 +
:<tt>$HOME/.var/app/org.gnucash.GnuCash/</tt> and
 +
:<tt>$HOME/.local/share/flatpak/app/org.gnucash.GnuCash/</tt>
  
 
=Known Issues=
 
=Known Issues=
−
* To use '''smart cards''', at least [https://www.fosslinux.com/13357/new-flatpak-1-3-2-uses-custom-fuse-filesystem-installation-technique.htm Flatpak 1.3.2] needs to be installed on your system. Complain against your distribution if they do not offer it.
+
;Architecture: While the ''program'' <tt>flatpak</tt> supports many architectures, it appears that the ''service'' [{{URL:FH}} flathub.org] dropped support for new
−
* no ''direct report printing'' (printing to file works) and
+
:* <tt>i386</tt> packages sometime between September and December 2019, the release dates for GnuCash 3.7 and 3.8 respectively and
−
* a potential bug that causes guile to attempt to recompile all scm sources: {{Flatpak_Guile_Error_Demo}}
+
:* 32-bit arm packages after GnuCash 4.4.
−
* [https://github.com/flathub/org.gnucash.GnuCash/issues/ Current list]
+
:The [[#Nightly_Test_Versions_at_gnucash.org|nightly builds on code.gnucash.org]] are <tt>x86_64</tt> only.
 +
* We do not ship the [[Python Bindings]],
 +
* no ''direct report printing'', but printing them to file and direct printing of checks works and
 +
* '''Nvidia GPU'''
 +
:Linux has had ongoing issues with Nvidia graphics drivers since early 2023. If you have an Nvidia GPU and GnuCash can't display reports or crashes when you try, run
 +
  flatpak run --env=WEBKIT_DISABLE_COMPOSITING_MODE=1 org.gnucash.GnuCash
 +
* '''Potential loss of settings'''
 +
:This happens when a few conditions coincide
 +
:* On your host system you are using (or have been using) GnuCash 4.7 or older
 +
:* You install or upgrade to flatpak GnuCash 4.5 or newer
 +
 
 +
:Under these conditions your flatpak GnuCash preferences will be reset due to changes internal to flatpak itself. We have created a fix for this in GnuCash 4.7 (native) in combination with flatpak GnuCash 4.8-1. Unfortunately this fix can only work if you have run GnuCash 4.7 (or more recent) at least once natively on your host system before running GnuCash 4.8-1 or more recent in flatpak. This is currently (at the time of the flatpak 4.8-1 release) unlikely to happen unless the user makes quite an effort. Over time this situation will improve.
 +
 
 +
:'''How to fix'''
 +
:In case you hit this issue there are a few ways forward:
 +
:* If you can run GnuCash 4.7+ natively on your host and you have installed GnuCash flatpak 4.8-1+
 +
::* do run GnuCash 4.7+ natively at least once and
 +
::* (re)move the file ''$HOME/.var/app/org.gnucash.GnuCash/config/glib-2.0/settings/keyfile''. The next time you start GnuCash flatpak it will import your preferences from your host GnuCash.
 +
:* If you're not in a position you can run GnuCash 4.7+ natively on your host and you didn't tweak a lot of preferences
 +
::* the easiest fix then is probably to manually go through and set the preferences you tweaked before the first time you start flatpak GnuCash 4.5 or above. They should stay set after that.
 +
:* If you do want to restore your preferences while not able to run GnuCash 4.7+ natively on your host
 +
::* you can run the following commands in a shell: {{Flatpak convert-pref.sh}}
 +
 
 +
:For the nitty-gritty details that causes this issue, refer to [{{URL:Bugs}}show_bug.cgi?id=798194 Bug 798194]
 +
 
 +
* [{{URL:GH}}flathub/org.gnucash.GnuCash/issues/ Current list]
 +
 
 +
==Resolved==
 +
* To use '''smart cards''':
 +
*# At least [https://www.fosslinux.com/13357/new-flatpak-1-3-2-uses-custom-fuse-filesystem-installation-technique.htm Flatpak 1.3.2] needs to be installed on your system.
 +
*# Because the [{{URL:Bugs}}show_bug.cgi?id=798326 software on our build server is to old], you have to follow the instructions in [[#Granting Access to Other Resources]].
 +
* All ''current'' versions are '''''PSD2'' capable'''—an EU directive—of online banking via ''[[:Category:De/FinTS|FinTS]]''/''[[De/Online-Banking|Online-Banking (german)]]'' protocol.
 +
* Current versions of GnuCash flatpak will no longer attempt to recompile all scm sources though it will continue to emit warnings about obsolete .go files: {{Flatpak_Guile_Error_Demo}}
 +
 
 +
=Flatpak Documentation=
 +
* [{{URL:FP-docs}}introduction.html Overview]
 +
* [{{URL:FP-docs}}using-flatpak.html Usage Instructions]
 +
* [{{URL:FP-docs}}flatpak-command-reference.html Command Reference]
  
 
=Installation=
 
=Installation=
−
Examples for ''Ubuntu'' or ''Debian'' (in ''Buster'', ''Flatpak'' is already included, for ''Stretch'' and ''Jessie'' backports exist):
+
You can configure many package managers like <tt>Gnome Software</tt> or KDE's <tt>Discover</tt> to at least install or update Flatpaks from Flathub, but on this page we will use the more powerful <tt>flatpak</tt> command line tool.
−
;Hint: For other distributions replace <tt>apt* <command></tt> by your preferred commandline software managment tool and its command, i.e. <SyntaxHighlight lang="sh">zypper install flatpak
+
The examples to install flatpak itself are written for ''Debian'' (in ''Buster'' ''Flatpak'' is already included, for ''Stretch'' and ''Jessie'' backports exist) and its derivates like ''Ubuntu''.
−
</Syntaxhighlight> for many rpm based distributions.
+
;Hint: For other distributions replace <tt>apt* <command></tt> by your preferred commandline software managment tool and its command, i.e. for many rpm based distributions <SyntaxHighlight lang="sh">zypper install flatpak
 +
</Syntaxhighlight> FlatPak.org offers [{{URL:FP}}setup Instructions for several distributions].
 +
;Annotation for the following examples: <tt>sudo</tt> is not required. <tt>flatpak</tt> is smart enough to ask on demand your desktop for the dialog like under KDE: [[File:FP-Auhentication-KDE.png]]
  
−
==Regular releases from ''flathub.org''==
+
==Regular releases at ''flathub.org''==
 
You can have both the ''regular'', currently GnuCash {{Version}}, and ''beta'' branches installed at the same time.
 
You can have both the ''regular'', currently GnuCash {{Version}}, and ''beta'' branches installed at the same time.
 +
 +
;Note:The current versions contain Aqbanking {{AqB_Version}}.
  
 
'''Beta'''s (GnuCash {{BetaSeries}}) are previews and only released in the last months before the next main version, see [[Release Schedule]].
 
'''Beta'''s (GnuCash {{BetaSeries}}) are previews and only released in the last months before the next main version, see [[Release Schedule]].
−
:;See also [https://flathub.org/apps/details/org.gnucash.GnuCash Flathub]
+
:;See also [{{URL:FP}}apps/details/org.gnucash.GnuCash Flathub]
  
 
;For Stable Releases: {{Install_Flatpak_sh}}
 
;For Stable Releases: {{Install_Flatpak_sh}}
 +
;Default App Installation Locations
 +
<nowiki>
 +
--system (for all users, default)    /var/lib/flatpak
 +
--user                              ~/.local/share/flatpak</nowiki>
 
;:Tip: To get the most recent version, run each quarter year (see [[Release Schedule]]): <SyntaxHighlight lang="sh">
 
;:Tip: To get the most recent version, run each quarter year (see [[Release Schedule]]): <SyntaxHighlight lang="sh">
 
flatpak update
 
flatpak update
Line 30: Line 79:
 
;For Unstable (i.e., beta) Releases: Do the process for stable releases, but ''register'', ''install'', and ''run'' as follows. {{Install_Flatpak_Unstable_sh}}
 
;For Unstable (i.e., beta) Releases: Do the process for stable releases, but ''register'', ''install'', and ''run'' as follows. {{Install_Flatpak_Unstable_sh}}
  
−
==Test version from ''gnucash.org''==
+
;Downgrading: It can't be done from the average package manager, but it can be done from the command line. It's a two-step command: <SyntaxHighlight lang="sh">
 +
flatpak remote-info --log flathub org.gnucash.GnuCash # list all commits in the repo
 +
flatpak update --commit=HASH --appstream flathub org.gnucash.GnuCash # checkout commit HASH in the repo
 +
</Syntaxhighlight> The <code>appstream</code> argument isn't needed if you have only one repository configured for org.gnucash.GnuCash.
 +
 
 +
==<q>Nightly</q> Test Versions at ''gnucash.org''==
 
;Warning:Save your data before using test versions!
 
;Warning:Save your data before using test versions!
 
Often you can find test versions on the [{{BuildURL}}/builds/flatpak/ build-server]. They come in two flavours:
 
Often you can find test versions on the [{{BuildURL}}/builds/flatpak/ build-server]. They come in two flavours:
−
:;Maint: Version {{Version}} plus ''all recent'' bug fixes, but no new features: [{{BuildURL}}/builds/flatpak/maint/?C=M;O=D {{BuildServer}}/builds/flatpak/maint/]
+
:;Stable: Version {{Version}} plus ''all recent'' bug fixes, but no new features:
−
:;Master: Version {{Version}} plus new features, but bug fixes can be ''delayed'' a few days: [{{BuildURL}}/builds/flatpak/master/?C=M;O=D {{BuildServer}}/builds/flatpak/master/]
+
::[{{URL:Build:FP}} {{URL:Build:FP}}]
 +
:;Future: Only available after the implementation of a feature from [[Release Schedule#Goals for 6.0]]!
 +
:;The branches were named <code>maint</code> and <code>master</code> before the GnuCash 5.0 release.
 +
::Version {{Version}} plus new features, but bug fixes can be ''delayed'' a few days:
 +
::[{{URL:Build:FP|future}} {{URL:Build:FP|future}}]
 
;Tip: The file names in these directories can be used in the example below after trimming the „<tt>gnucash-</tt>“ prefix and „<tt>.flatpakref</tt>“ suffix.
 
;Tip: The file names in these directories can be used in the example below after trimming the „<tt>gnucash-</tt>“ prefix and „<tt>.flatpakref</tt>“ suffix.
  
−
The current version contains Aqbanking 6.1.0 ('''''PSD2'' capable''' of online banking via ''[[:Category:De/FinTS|FinTS]]''/''[[De/HBCI|HBCI (german)]]'' protocol; date of this information: 2020-02-20).
+
;Note:The current version contains Aqbanking {{AqB_Version_nightly_FP}}.
  
 
<SyntaxHighlight lang="sh">
 
<SyntaxHighlight lang="sh">
Line 49: Line 107:
 
# org.gnucash.GnuCash.Debug
 
# org.gnucash.GnuCash.Debug
 
# org.gnucash.GnuCash.Locale
 
# org.gnucash.GnuCash.Locale
−
sudo flatpak --arch=x86_64 install gnucash org.gnucash.GnuCash//maint-C3.8b-163-g0e6c9e219-D3.8b-15-g0479ece # <-- change version here!
+
sudo flatpak --arch=x86_64 install gnucash org.gnucash.GnuCash//stable-C5.8-20-ga84189b79d-D5.7-2-ge45aa63c # <-- change version here!
 
flatpak run org.gnucash.GnuCash  # start program
 
flatpak run org.gnucash.GnuCash  # start program
 
</Syntaxhighlight>
 
</Syntaxhighlight>
 
;Note: <tt>flatpak --arch=x86_64</tt> is only required, if you have a 64-bit processor with a 32-bit OS.
 
;Note: <tt>flatpak --arch=x86_64</tt> is only required, if you have a 64-bit processor with a 32-bit OS.
 +
 +
==Getting Older Releaseses==
 +
There may be occasions where you would like to install an older version of GnuCash - an important bug in the most recent version prevents you from upgrading, you may want to do regression tests, ...
 +
While flathub by default will install or upgrade to the most recent version, it also provides access to a number of older versions. Here is how you can downgrade to one such version from the command line:
 +
 +
# Install current gnucash<SyntaxHighlight lang="sh">$ flatpak install flathub org.gnucash.GnuCash</SyntaxHighlight>
 +
# List all gnucash packages that are available in flathub<SyntaxHighlight lang="sh">$ flatpak remote-info --log flathub org.gnucash.GnuCash
 +
        ID: org.gnucash.GnuCash
 +
      Ref: app/org.gnucash.GnuCash/x86_64/stable
 +
      Arch: x86_64
 +
    Branch: stable
 +
Collection: org.flathub.Stable
 +
  Download: 110,5 MB
 +
Installed: 319,5 MB
 +
  Runtime: org.gnome.Platform/x86_64/43
 +
      Sdk: org.gnome.Sdk/x86_64/43
 +
 +
    Commit: 612379218b8be2d2dba316db580154efd4521d35f24f9500c3eafe4694dfe4ea
 +
    Parent: c3d6b1ff9fb14beb33d26d11068c4f40fb9cf400c14f090b8f24f077205b173d
 +
  Subject: Package gnucash 5.1 (16bb64cf)
 +
      Date: 2023-05-04 15:46:25 +0000
 +
  History:
 +
 +
    Commit: c3d6b1ff9fb14beb33d26d11068c4f40fb9cf400c14f090b8f24f077205b173d
 +
  Subject: Package gnucash 5.0-1 (6a579a23)
 +
      Date: 2023-03-29 00:17:36 +0000
 +
 +
    Commit: 08e6ac442846255491fa72592cd8451e274efd7649e430d9f968adc6f0e723f3
 +
  Subject: Package GnuCash 5.0 (c9b14ae9)
 +
      Date: 2023-03-26 20:34:31 +0000
 +
 +
    Commit: 511cf18127561c55b5999121c6b301ca1e90d6cc988a00701257606df7fae86f
 +
  Subject: Release GnuCash 4.14 (b2942403)
 +
      Date: 2023-03-25 23:27:27 +0000
 +
 +
    Commit: eb1be08966b94073a6f219dcf8f61f42c88228d1d1f2aba15da990591bccf3c7
 +
  Subject: Fix GnuCash tarball sha256 (bd9f8e1e)
 +
      Date: 2022-12-18 22:30:44 +0000
 +
 +
    Commit: 7e2d8364088a32d0f6849893a43b41a5623886c2d5c7da3505c023ba0c86fa5f
 +
  Subject: Fix GnuCash tarball sha256 (bd9f8e1e)
 +
      Date: 2022-12-18 22:30:44 +0000
 +
 +
    Commit: 75419560fa6ece2e44ca421e261266cd2469c43970f67ad5d9498cb952274b84
 +
  Subject: Fix Flathub build id. (98f80163)
 +
      Date: 2022-10-23 00:28:02 +0000
 +
 +
    Commit: dc06bee16009e51bfe041891feb8ec36e282b732e87702a2ad914913ec2ea675
 +
  Subject: Package gnucash 4.12-2 (5b8ae13f)
 +
      Date: 2022-10-22 22:51:18 +0000
 +
 +
    Commit: 24135ed2a3a1ed806df526a632ad1d178039648e0c620478dd1bab50312c22e3
 +
  Subject: Package gnucash 4.12-1. (b335bd5a)
 +
      Date: 2022-10-16 14:19:27 +0000
 +
 +
    Commit: 98bea86b69a63cc6ed5a1854344d115a683d6cee7ca56b81e7210f2da2706d88
 +
  Subject: Package gnucash 4.12. (fea1ed21)
 +
      Date: 2022-09-25 18:36:54 +0000
 +
</SyntaxHighlight>
 +
# Take note of the commit hash (the long string of digits and letters) for the gnucash version you want to install. For example to install gnucash 4.14, the relevant commit hash would be 511cf18127561c55b5999121c6b301ca1e90d6cc988a00701257606df7fae86f
 +
# Upgrade/Downgrade gnucash to the version you like<SyntaxHighlight lang="sh">$ flatpak update --commit <commit-hash> org.gnucash.GnuCash</SyntaxHighlight>For the example of upgrading to 4.14, this would become<br/><SyntaxHighlight lang="sh">$ flatpak update --commit 511cf18127561c55b5999121c6b301ca1e90d6cc988a00701257606df7fae86f org.gnucash.GnuCash</SyntaxHighlight>
 +
 +
==Selecting the GnuCash version to run==
 +
To list the installed versions:
 +
    flatpak info org.gnucash.GnuCash
 +
To run an installed version other than the default:
 +
    flatpak run --branch <version> org.gnucash.GnuCash
 +
To change the default version:
 +
    flatpak make-current org.gnucash.GnuCash <version>
 +
As always you can use <code>--system</code> or <code>--user</code> to distinguish between system-wide and user-space installations.
 +
 +
=Configuration=
 +
==Granting Access to Other Resources==
 +
As each Flatpak app runs in a sandbox, you have to unlock additionally required resources like
 +
;USB or Network Drive:
 +
:;with fix mountpoint: {{Flatpak overwrite-fs.sh}}
 +
:;with changing mountpoint: {{Flatpak overwrite-vfs.sh}}
 +
::Now GnuCash Flatpak can see the share under <tt>Other Locations</tt> when it is mounted. <ref>From [{{URL:reddit}}r/pop_os/comments/1702jkd/ reddit: Flatpak app don't seemed to have access to network drives]</ref>
 +
;Smartcard Reader: To use smart cards in [[AqBanking]]
 +
:# on the host—your Linux PC—the demon <tt>pcscd</tt> must be running,
 +
:# the related socket must become unlocked for your GnuCash-Flatpak once: {{Flatpak_PCSC_Socket.sh}}
 +
<tt>sudo</tt> may be required depending on the rest of your installation.
 +
;See also: {{URL:FP-docs}}sandbox-permissions.html
 +
 +
==Changing the Locale==
 +
Refer to [[Locale Settings]] to determine the settings required.
 +
 +
Refer to [[Configuration_Locations#System-wide|Configuration Locations - System-wide]] for instructions on how to change Flatpak environment variables using ''flatpak override''.
  
 
=Tips=
 
=Tips=
−
==Maintenance==
 
−
You should — also if no new GnuCash version was announced — sometimes run <syntaxhighlight lang="sh">[sudo] flatpak update</syntaxhighlight> to to look for updated components of your Flatpak environment. That might look like: {{Flatpak_update_sh}} It is primarly important, if you reported a '''problem''' about which the Gnucash-Developers said, its cause lies not in Gnucash but one of the by Flatpak installed Gnome libraries. But  also for  '''security reason'''s you should keep your environment up to date.
 
−
 
 
==Getting Console Output==
 
==Getting Console Output==
 
In case of trouble get the ''console output'': <Syntaxhighlight lang="sh>flatpak run org.gnucash.GnuCash</Syntaxhighlight>
 
In case of trouble get the ''console output'': <Syntaxhighlight lang="sh>flatpak run org.gnucash.GnuCash</Syntaxhighlight>
Line 66: Line 209:
  
 
==Using Command Line Tools==
 
==Using Command Line Tools==
−
To call ''command line'' tools like <tt>aqbanking-cli</tt> <Syntaxhighlight lang="sh>
+
To call ''command line'' tools like <tt>aqbanking-cli</tt>, the following opens a command shell inside the sandbox of GnuCash.{{Flatpak_Shell_sh}}
−
flatpak run --command=sh org.gnucash.GnuCash
+
Inside you can call related shell commands for [[AqBanking|Online Banking]] like <tt>aqbanking-cli</tt>… or [[Online Quotes]] <tt>gnc-fq-*</tt> etc.  However, <tt>gnc-fq-update</tt> does not work.
−
</Syntaxhighlight> opens a shell inside the sandbox of GnuCash.
+
;Example <q>Query Versions</q>: This is required on bug reporting. {{Flatpak Versions}}
 +
;Example <q>Fetch Online Quotes</q>: The following enters the GnuCash sandbox and runs a <tt>gnucash-cli</tt> command in a single line (using the example of getting price quotes). This can be useful for automation, i.e. creating a modern [{{URL:wp}}Systemd systemd] timer or a classical [{{URL:wp}}Cron cron] job to get price quotes on a regular basis. {{Flatpak_Quotes_sh}}
 +
:;Attention:Notice the order of the arguments!
 +
 
 +
==Desktop Icon==
 +
Assuming you want to create a desktop icon to open your second file <tt>test-2.gnucash</tt> from your <tt>Documents</tt> folder:<syntaxhighlight lang="ini">
 +
[Desktop Entry]
 +
Type=Application
 +
Terminal=false
 +
Exec=flatpak run org.gnucash.GnuCash Documents/test-2.gnucash
 +
Name=GnuCash (flatpak) test-2
 +
Comment=Accounting for my alter ego
 +
Icon=~/.local/share/flatpak/app/org.gnucash.GnuCash/x86_64/stable/active/files/share/gnucash/pixmaps/gnucash-icon.ico
 +
</syntaxhighlight> <ref>[{{ListURL}}/pipermail/gnucash-user/2022-March/100399.html User discussion in March 2022]</ref>, <ref>[{{URL:XDG-spec}}desktop-entry-spec/desktop-entry-spec-latest.html Desktop Entry Specification]</ref>
 +
;Notes:
 +
::;Terminal: Enable it while debugging to see concole output.
 +
::;Exec, Name: Replace <tt>test-2.gnucash</tt> by your real filename.
 +
::;Comment: Whatever makes sense for you.
 +
::;Icon:
 +
::# Replace <tt>~/.local/share</tt> by <tt>/var/lib</tt> if you installed with -<tt>-system</tt> option.
 +
::# Replace <tt>x86_64</tt> by <tt>i386</tt> or whatever you used at installation with the <tt>--arch</tt> option.
 +
 
 +
==SQL Connection==
 +
Use <tt>127.0.0.1</tt> instead of <tt>localhost</tt>. The latter will tell the mysql client to use unix file sockets. These are not permitted by default by the flatpak sandbox. You can [[#Granting Access to Other Resources|enable permissions]] for this on your gnucash flatpak, though I don't know offhand where the unix socket is located. You'll have to figure that out first (it will look like a file on your system somewhere) and then use the flatpak override commmand to tell it to allow access to that file for the <tt>org.gnucash.GnuCash</tt> package.
 +
 
 +
Using 127.0.0.1 on the other hand will force mysql to use a real network connection. Those are not restricted in the GnuCash flatpak.
 +
 
 +
More details: [}}URL:GH}}flathub/org.gnucash.GnuCash/issues/17 FlatHub GnuCash issue 17]
 +
 
 +
==Maintenance==
 +
===Overview===
 +
If you forgot which parts were installed and in which mode, run {{Flatpak list con}} This user has a system and a user installation and did not clean up it on a regular base. There is
 +
* a system wide stable version from flathub and
 +
* a user specific from <tt>gnc-testing-repo</tt> which contains [{{URL:GH}}Gnucash/gnucash-on-flatpak#readme self built] versions.
 +
;Note: You can learn more about the [{{URL:FP-docs}}available-runtimes.html#available-runtimes Available Runtimes], [{{URL:FP-docs}}sandbox-permissions-reference.html#sandbox-permissions-reference Sandbox Permissions Reference] …
 +
 
 +
===Update===
 +
You should — also if no new GnuCash version was announced — sometimes run <syntaxhighlight lang="sh">
 +
sudo flatpak update  # sudo is only required for systemwide installations
 +
</syntaxhighlight> to look for updated components of your Flatpak environment. That might look like: {{Flatpak_update_sh}} It is primarly important, if you reported a '''problem''' about which the Gnucash-Developers said, its cause lies not in Gnucash but one of the by Flatpak installed Gnome libraries. But  also for  '''security reason'''s you should keep your environment up to date.
 +
 
 +
===Cleanup===
 +
As there might now be some obsolate parts, you should run {{Flatpak Cleanup con}} The pinned modules are still in use by your apps.
  
−
==Granting Access to Other Resources==
 
−
Each flatpak is a sandbox. To allow it e.g. access to your USB drive, execute <syntaxhighlight lang="sh">
 
−
sudo flatpak override org.gnucash.GnuCash --filesystem=<path-to-your-usb>
 
−
</syntaxhighlight>
 
−
;See also: https://docs.flatpak.org/en/latest/sandbox-permissions.html
 
 
==Crash: Stacktrace==
 
==Crash: Stacktrace==
−
{{Flatpak-coredumpctl_hlp}}
+
[{{URL:FP-docs}}debugging.html Flatpak Debugging] has instructions for running gdb in a flatpak round out the gdb instructions in [[Stack_Trace]]. An alternative if you have <tt>systemd-coredump</tt> installed (it's there by default in Fedora 28 and later) you can use [https://www.figuiere.net/technotes/notes/tn001/|flathub-coredumpctl] to easily generate a stack trace (in gdb <code>where</code> and <code>bt</code> are synonyms).
 +
 
 +
==GTK Inspector==
 +
{{Flatpak-gtk-inspector}}
  
 
==Other==
 
==Other==
 
;[[De/Flatpak/Migrationsanleitung|Migration]] from normal package to ''flatpak'' (german)
 
;[[De/Flatpak/Migrationsanleitung|Migration]] from normal package to ''flatpak'' (german)
−
[[Category:Flatpak|en]]
 

Latest revision as of 21:09, 2 September 2024

Languages Deutsch

Flatpaks are bundles which besides the program also contain all required libraries. Use cases:

  • If your Linux distribution is too old to offer all required libraries but has Flatpak support, you can install a recent released version of GnuCash from the FlatHub repository.
  • If a developer or a translator asks you to test their recent work, you can use a nightly version from our Flatpak repository.

Note flatpak's Sandbox concept: it uses files in

$HOME/.var/app/org.gnucash.GnuCash/ and
$HOME/.local/share/flatpak/app/org.gnucash.GnuCash/

Known Issues

Architecture
While the program flatpak supports many architectures, it appears that the service flathub.org dropped support for new
  • i386 packages sometime between September and December 2019, the release dates for GnuCash 3.7 and 3.8 respectively and
  • 32-bit arm packages after GnuCash 4.4.
The nightly builds on code.gnucash.org are x86_64 only.
  • We do not ship the Python Bindings,
  • no direct report printing, but printing them to file and direct printing of checks works and
  • Nvidia GPU
Linux has had ongoing issues with Nvidia graphics drivers since early 2023. If you have an Nvidia GPU and GnuCash can't display reports or crashes when you try, run
  flatpak run --env=WEBKIT_DISABLE_COMPOSITING_MODE=1 org.gnucash.GnuCash
  • Potential loss of settings
This happens when a few conditions coincide
  • On your host system you are using (or have been using) GnuCash 4.7 or older
  • You install or upgrade to flatpak GnuCash 4.5 or newer
Under these conditions your flatpak GnuCash preferences will be reset due to changes internal to flatpak itself. We have created a fix for this in GnuCash 4.7 (native) in combination with flatpak GnuCash 4.8-1. Unfortunately this fix can only work if you have run GnuCash 4.7 (or more recent) at least once natively on your host system before running GnuCash 4.8-1 or more recent in flatpak. This is currently (at the time of the flatpak 4.8-1 release) unlikely to happen unless the user makes quite an effort. Over time this situation will improve.
How to fix
In case you hit this issue there are a few ways forward:
  • If you can run GnuCash 4.7+ natively on your host and you have installed GnuCash flatpak 4.8-1+
  • do run GnuCash 4.7+ natively at least once and
  • (re)move the file $HOME/.var/app/org.gnucash.GnuCash/config/glib-2.0/settings/keyfile. The next time you start GnuCash flatpak it will import your preferences from your host GnuCash.
  • If you're not in a position you can run GnuCash 4.7+ natively on your host and you didn't tweak a lot of preferences
  • the easiest fix then is probably to manually go through and set the preferences you tweaked before the first time you start flatpak GnuCash 4.5 or above. They should stay set after that.
  • If you do want to restore your preferences while not able to run GnuCash 4.7+ natively on your host
  • you can run the following commands in a shell: 
    # Backup your current sandbox settings:
cp $HOME/.var/app/org.gnucash.GnuCash/config/glib-2.0/settings/keyfile \
  $HOME/gnucash-settings.save
# Real conversion:
dconf dump /org/gnucash/ > \
  $HOME/.var/app/org.gnucash.GnuCash/config/glib-2.0/settings/keyfile
perl -pi.bkp -e's!^[[]![org/gnucash/!' \
  $HOME/.var/app/org.gnucash.GnuCash/config/glib-2.0/settings/keyfile
For the nitty-gritty details that causes this issue, refer to Bug 798194

Resolved

  • To use smart cards:
    1. At least Flatpak 1.3.2 needs to be installed on your system.
    2. Because the software on our build server is to old, you have to follow the instructions in #Granting Access to Other Resources.
  • All current versions are PSD2 capable—an EU directive—of online banking via FinTS/Online-Banking (german) protocol.
  • Current versions of GnuCash flatpak will no longer attempt to recompile all scm sources though it will continue to emit warnings about obsolete .go files: 
    :
;;; note: source file /app/share/guile//2.2/ice-9/eval.scm
;;;       newer than compiled /app/lib/guile/2.2/ccache/ice-9/eval.go
:
Workaround: 
# --system install
cd /var/lib/flatpak/app/org.gnucash.GnuCash
# OR --user install
cd $HOME/.local/share/flatpak/app/org.gnucash.GnuCash

sudo find . -name '*.go' -exec touch '{}' ';'

Flatpak Documentation

Installation

You can configure many package managers like Gnome Software or KDE's Discover to at least install or update Flatpaks from Flathub, but on this page we will use the more powerful flatpak command line tool. The examples to install flatpak itself are written for Debian (in Buster Flatpak is already included, for Stretch and Jessie backports exist) and its derivates like Ubuntu.

Hint
For other distributions replace apt* <command> by your preferred commandline software managment tool and its command, i.e. for many rpm based distributions 
zypper install flatpak
FlatPak.org offers Instructions for several distributions.
Annotation for the following examples
sudo is not required. flatpak is smart enough to ask on demand your desktop for the dialog like under KDE: FP-Auhentication-KDE.png

Regular releases at flathub.org

You can have both the regular, currently GnuCash 5.10, and beta branches installed at the same time.

Note
The current versions contain Aqbanking 6.5.4.

Betas (GnuCash 5.9xx) are previews and only released in the last months before the next main version, see Release Schedule.

See also Flathub
For Stable Releases
# Install FlatPak (on debian based distributions, others have to replace 'apt-get install'):
sudo apt-get install flatpak

# Register FlatHub repository for a system app (available to all users):
sudo flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
# or only you:
flatpak remote-add --user --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo

# Install GnuCash ...
# for all users:
#  sudo is only needed for a --system install, if the user is not in the 'sudo' group
#  --system is the default if --user is not specified
sudo flatpak install --system flathub org.gnucash.GnuCash
# or only you:
flatpak install --user flathub org.gnucash.GnuCash

# Run GnuCash:
flatpak run org.gnucash.GnuCash
Default App Installation Locations
 --system (for all users, default)    /var/lib/flatpak
 --user                               ~/.local/share/flatpak
Tip
To get the most recent version, run each quarter year (see Release Schedule): 
flatpak update
For Unstable (i.e., beta) Releases
Do the process for stable releases, but register, install, and run as follows. 
# Register:
flatpak remote-add --user --if-not-exists flathub https://flathub.org/beta-repo/flathub-beta.flatpakrepo
# Install
flatpak install --user flathub-beta org.gnucash.GnuCash
# Run
flatpak run --branch=beta org.gnucash.GnuCash
Downgrading
It can't be done from the average package manager, but it can be done from the command line. It's a two-step command: 
flatpak remote-info --log flathub org.gnucash.GnuCash # list all commits in the repo
flatpak update --commit=HASH --appstream flathub org.gnucash.GnuCash # checkout commit HASH in the repo
The appstream argument isn't needed if you have only one repository configured for org.gnucash.GnuCash.

Nightly Test Versions at gnucash.org

Warning
Save your data before using test versions!

Often you can find test versions on the build-server. They come in two flavours:

Stable
Version 5.10 plus all recent bug fixes, but no new features:
https://code.gnucash.org/builds/flatpak/stable/?C=M;O=D
Future
Only available after the implementation of a feature from Release Schedule#Goals for 6.0!
The branches were named maint and master before the GnuCash 5.0 release.
Version 5.10 plus new features, but bug fixes can be delayed a few days:
https://code.gnucash.org/builds/flatpak/future/?C=M;O=D
Tip
The file names in these directories can be used in the example below after trimming the „gnucash-“ prefix and „.flatpakref“ suffix.
Note
The current version contains Aqbanking 6.5.12beta.
sudo apt install flatpak  #install Flatpak
# register repositories:
sudo flatpak remote-add --if-not-exists gnucash https://code.gnucash.org/builds/flatpak/gnucash-nightlies.flatpakrepo
sudo flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
flatpak --arch=x86_64 remote-ls gnucash  # show all packages
# output should be:
# org.gnucash.GnuCash
# org.gnucash.GnuCash.Debug
# org.gnucash.GnuCash.Locale
sudo flatpak --arch=x86_64 install gnucash org.gnucash.GnuCash//stable-C5.8-20-ga84189b79d-D5.7-2-ge45aa63c  # <-- change version here!
flatpak run org.gnucash.GnuCash  # start program
Note
flatpak --arch=x86_64 is only required, if you have a 64-bit processor with a 32-bit OS.

Getting Older Releaseses

There may be occasions where you would like to install an older version of GnuCash - an important bug in the most recent version prevents you from upgrading, you may want to do regression tests, ... While flathub by default will install or upgrade to the most recent version, it also provides access to a number of older versions. Here is how you can downgrade to one such version from the command line:

  1. Install current gnucash
    $ flatpak install flathub org.gnucash.GnuCash
  2. List all gnucash packages that are available in flathub
    $ flatpak remote-info --log flathub org.gnucash.GnuCash
        ID: org.gnucash.GnuCash
       Ref: app/org.gnucash.GnuCash/x86_64/stable
      Arch: x86_64
    Branch: stable
Collection: org.flathub.Stable
  Download: 110,5 MB
 Installed: 319,5 MB
   Runtime: org.gnome.Platform/x86_64/43
       Sdk: org.gnome.Sdk/x86_64/43

    Commit: 612379218b8be2d2dba316db580154efd4521d35f24f9500c3eafe4694dfe4ea
    Parent: c3d6b1ff9fb14beb33d26d11068c4f40fb9cf400c14f090b8f24f077205b173d
   Subject: Package gnucash 5.1 (16bb64cf)
      Date: 2023-05-04 15:46:25 +0000
   History: 

    Commit: c3d6b1ff9fb14beb33d26d11068c4f40fb9cf400c14f090b8f24f077205b173d
   Subject: Package gnucash 5.0-1 (6a579a23)
      Date: 2023-03-29 00:17:36 +0000

    Commit: 08e6ac442846255491fa72592cd8451e274efd7649e430d9f968adc6f0e723f3
   Subject: Package GnuCash 5.0 (c9b14ae9)
      Date: 2023-03-26 20:34:31 +0000

    Commit: 511cf18127561c55b5999121c6b301ca1e90d6cc988a00701257606df7fae86f
   Subject: Release GnuCash 4.14 (b2942403)
      Date: 2023-03-25 23:27:27 +0000

    Commit: eb1be08966b94073a6f219dcf8f61f42c88228d1d1f2aba15da990591bccf3c7
   Subject: Fix GnuCash tarball sha256 (bd9f8e1e)
      Date: 2022-12-18 22:30:44 +0000

    Commit: 7e2d8364088a32d0f6849893a43b41a5623886c2d5c7da3505c023ba0c86fa5f
   Subject: Fix GnuCash tarball sha256 (bd9f8e1e)
      Date: 2022-12-18 22:30:44 +0000

    Commit: 75419560fa6ece2e44ca421e261266cd2469c43970f67ad5d9498cb952274b84
   Subject: Fix Flathub build id. (98f80163)
      Date: 2022-10-23 00:28:02 +0000

    Commit: dc06bee16009e51bfe041891feb8ec36e282b732e87702a2ad914913ec2ea675
   Subject: Package gnucash 4.12-2 (5b8ae13f)
      Date: 2022-10-22 22:51:18 +0000

    Commit: 24135ed2a3a1ed806df526a632ad1d178039648e0c620478dd1bab50312c22e3
   Subject: Package gnucash 4.12-1. (b335bd5a)
      Date: 2022-10-16 14:19:27 +0000

    Commit: 98bea86b69a63cc6ed5a1854344d115a683d6cee7ca56b81e7210f2da2706d88
   Subject: Package gnucash 4.12. (fea1ed21)
      Date: 2022-09-25 18:36:54 +0000
  3. Take note of the commit hash (the long string of digits and letters) for the gnucash version you want to install. For example to install gnucash 4.14, the relevant commit hash would be 511cf18127561c55b5999121c6b301ca1e90d6cc988a00701257606df7fae86f
  4. Upgrade/Downgrade gnucash to the version you like
    $ flatpak update --commit <commit-hash> org.gnucash.GnuCash
    For the example of upgrading to 4.14, this would become
    $ flatpak update --commit 511cf18127561c55b5999121c6b301ca1e90d6cc988a00701257606df7fae86f org.gnucash.GnuCash

Selecting the GnuCash version to run

To list the installed versions: 

   flatpak info org.gnucash.GnuCash

To run an installed version other than the default: 

   flatpak run --branch <version> org.gnucash.GnuCash

To change the default version: 

   flatpak make-current org.gnucash.GnuCash <version>

As always you can use --system or --user to distinguish between system-wide and user-space installations.

Configuration

Granting Access to Other Resources

As each Flatpak app runs in a sandbox, you have to unlock additionally required resources like

USB or Network Drive
with fix mountpoint
# After configuring automatic mounting of the drive in the host system
sudo flatpak override org.gnucash.GnuCash --filesystem=$PATH_TO_DRIVE
with changing mountpoint
sudo flatpak override org.gnucash.GnuCash --talk-name=org.gtk.vfs.* --filesystem=xdg-run/gvfs
Now GnuCash Flatpak can see the share under Other Locations when it is mounted. [1]
Smartcard Reader
To use smart cards in AqBanking
  1. on the host—your Linux PC—the demon pcscd must be running,
  2. the related socket must become unlocked for your GnuCash-Flatpak once: 
    sudo flatpak override org.gnucash.GnuCash --socket=pcsc

sudo may be required depending on the rest of your installation.

See also
https://docs.flatpak.org/en/latest/sandbox-permissions.html

Changing the Locale

Refer to Locale Settings to determine the settings required.

Refer to Configuration Locations - System-wide for instructions on how to change Flatpak environment variables using flatpak override.

Tips

Getting Console Output

In case of trouble get the console output: 
flatpak run org.gnucash.GnuCash
or even better 
flatpak run org.gnucash.GnuCash --logto stdout

The latter will print all logs to the console rather than to an inaccessible trace file.

Using Command Line Tools

To call command line tools like aqbanking-cli, the following opens a command shell inside the sandbox of GnuCash.
flatpak run --command=sh org.gnucash.GnuCash

Inside you can call related shell commands for Online Banking like aqbanking-cli… or Online Quotes gnc-fq-* etc. However, gnc-fq-update does not work.

Example Query Versions
This is required on bug reporting. 
$ flatpak run --command=sh org.gnucash.GnuCash
[📦 org.gnucash.GnuCash ~]$ gnucash --version
GnuCash 3.8 development version
Build ID: git e6b3c56+(2020-01-26)
[📦 org.gnucash.GnuCash ~]$ aqbanking-cli versions
Versions:
 AqBanking-CLI: 6.0.2
 Gwenhywfar   : 5.1.3.0
 AqBanking    : 6.0.2.0
[📦 org.gnucash.GnuCash ~]$ exit
exits
Example Fetch Online Quotes
The following enters the GnuCash sandbox and runs a gnucash-cli command in a single line (using the example of getting price quotes). This can be useful for automation, i.e. creating a modern systemd timer or a classical cron job to get price quotes on a regular basis. 
flatpak run --command=gnucash-cli org.gnucash.GnuCash --quotes get /path/to/file.gnucash
Attention
Notice the order of the arguments!

Desktop Icon

Assuming you want to create a desktop icon to open your second file test-2.gnucash from your Documents folder:
[Desktop Entry]
Type=Application
Terminal=false
Exec=flatpak run org.gnucash.GnuCash Documents/test-2.gnucash
Name=GnuCash (flatpak) test-2
Comment=Accounting for my alter ego
Icon=~/.local/share/flatpak/app/org.gnucash.GnuCash/x86_64/stable/active/files/share/gnucash/pixmaps/gnucash-icon.ico
[2], [3]
Notes
Terminal
Enable it while debugging to see concole output.
Exec, Name
Replace test-2.gnucash by your real filename.
Comment
Whatever makes sense for you.
Icon
  1. Replace ~/.local/share by /var/lib if you installed with --system option.
  2. Replace x86_64 by i386 or whatever you used at installation with the --arch option.

SQL Connection

Use 127.0.0.1 instead of localhost. The latter will tell the mysql client to use unix file sockets. These are not permitted by default by the flatpak sandbox. You can enable permissions for this on your gnucash flatpak, though I don't know offhand where the unix socket is located. You'll have to figure that out first (it will look like a file on your system somewhere) and then use the flatpak override commmand to tell it to allow access to that file for the org.gnucash.GnuCash package.

Using 127.0.0.1 on the other hand will force mysql to use a real network connection. Those are not restricted in the GnuCash flatpak.

More details: [}}URL:GH}}flathub/org.gnucash.GnuCash/issues/17 FlatHub GnuCash issue 17]

Maintenance

Overview

If you forgot which parts were installed and in which mode, run 
$ flatpak list
Name                             Application ID                 Version  Zweig                                       Ursprung         Installation
default                          …eedesktop.Platform.GL.default          19.08                                       flathub          user
Mesa                             …eedesktop.Platform.GL.default 21.1.7   20.08                                       flathub          system
Mesa                             …eedesktop.Platform.GL.default 21.1.7   20.08                                       flathub          user
Mesa                             …eedesktop.Platform.GL.default 21.2.2   21.08                                       flathub          user
Intel                            …edesktop.Platform.VAAPI.Intel          19.08                                       flathub          user
Intel                            …edesktop.Platform.VAAPI.Intel          20.08                                       flathub          system
Intel                            …edesktop.Platform.VAAPI.Intel          20.08                                       flathub          user
Intel                            …edesktop.Platform.VAAPI.Intel          21.08                                       flathub          user
openh264                         …freedesktop.Platform.openh264 2.1.0    2.0                                         flathub          system
openh264                         …freedesktop.Platform.openh264 2.1.0    2.0                                         flathub          user
GNOME Application Platform vers… org.gnome.Platform                      3.38                                        flathub          user
GNOME Application Platform vers… org.gnome.Platform                      40                                          flathub          system
GNOME Application Platform vers… org.gnome.Platform                      40                                          flathub          user
GNOME Application Platform vers… org.gnome.Platform                      41                                          flathub          user
GNOME Software Development Kit … org.gnome.Sdk                           3.38                                        flathub          user
GNOME Software Development Kit … org.gnome.Sdk                           40                                          flathub          user
GNOME Software Development Kit … org.gnome.Sdk                           41                                          flathub          user
GnuCash                          org.gnucash.GnuCash                     4.8a+ (Flathub 4.8-1) stable                flathub          system
GnuCash                          org.gnucash.GnuCash            fbf8284+ maint-C4.8a-62-gfbf828476f-D4.8-3-g9d2b4e95 gnc-testing-repo user
This user has a system and a user installation and did not clean up it on a regular base. There is
  • a system wide stable version from flathub and
  • a user specific from gnc-testing-repo which contains self built versions.
Note
You can learn more about the Available Runtimes, Sandbox Permissions Reference …

Update

You should — also if no new GnuCash version was announced — sometimes run 
sudo flatpak update  # sudo is only required for systemwide installations
to look for updated components of your Flatpak environment. That might look like: 
        ID                                    Zweig  Op  Remote   Download
 1.     org.freedesktop.Platform.GL.default   19.08  u   flathub   < 85,1 MB
 2.     org.freedesktop.Platform.VAAPI.Intel  19.08  u   flathub    < 8,7 MB
 3.     org.gnome.Platform.Locale             3.34   u   flathub  < 322,2 MB (partial)
 4.     org.gnome.Platform                    3.34   u   flathub  < 320,4 MB
 5.     org.gnome.Sdk.Locale                  3.34   u   flathub  < 325,8 MB (partial)
 6.     org.gnome.Sdk                         3.34   u   flathub  < 663,9 MB

Proceed with these changes to the user installation? [Y/n]:
It is primarly important, if you reported a problem about which the Gnucash-Developers said, its cause lies not in Gnucash but one of the by Flatpak installed Gnome libraries. But also for security reasons you should keep your environment up to date.

Cleanup

As there might now be some obsolate parts, you should run 
$ flatpak uninstall --unused

These runtimes in installation 'user' are pinned and won't be removed; see flatpak-pin(1):
  runtime/org.gnome.Platform/x86_64/40
  runtime/org.gnome.Platform/x86_64/41
  runtime/org.gnome.Sdk/x86_64/40
  runtime/org.gnome.Sdk/x86_64/41


        KENNUNG                                       Zweig          Op
 1. [-] org.freedesktop.Platform.GL.default           19.08          r
 2. [-] org.freedesktop.Platform.VAAPI.Intel          19.08          r
 3. [-] org.gnome.Platform                            3.38           r
 4. [-] org.gnome.Platform.Locale                     3.38           r
 5. [-] org.gnome.Sdk                                 3.38           r
 6. [-] org.gnome.Sdk.Locale                          3.38           r

Uninstall complete.
The pinned modules are still in use by your apps.

Crash: Stacktrace

Flatpak Debugging has instructions for running gdb in a flatpak round out the gdb instructions in Stack_Trace. An alternative if you have systemd-coredump installed (it's there by default in Fedora 28 and later) you can use [1] to easily generate a stack trace (in gdb where and bt are synonyms).

GTK Inspector

flatpak run --env=GTK_DEBUG=interactive org.gnucash.GnuCash

Other

Migration from normal package to flatpak (german)
  1. ↑ From reddit: Flatpak app don't seemed to have access to network drives
  2. ↑ User discussion in March 2022
  3. ↑ Desktop Entry Specification
    4. Retrieved from "https://lists.gnucash.org/wiki/index.php?title=Flatpak&oldid=22200"