From 7f75affb0f4e5cc4f97637373a87f331df4eb3ee Mon Sep 17 00:00:00 2001 From: Patrick Griffis Date: Sun, 17 Dec 2023 13:56:43 -0600 Subject: [PATCH] Document HOST_XDG_* environment variables --- docs/conventions.rst | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/docs/conventions.rst b/docs/conventions.rst index 073f1bf1..959eb492 100644 --- a/docs/conventions.rst +++ b/docs/conventions.rst @@ -46,9 +46,9 @@ For some practical examples of bad IDs ``.desktop`` as a special case causing inconsistency. For this same reason, ``.Desktop`` suffixes should not be used for newly named applications. Don't hesitate to repeat the application name even if it already is part of the domain name section of the identifier (eg. ``org.example.Example``). - + - ``io.github.Foo`` - + This is problematic because while ``foo.github.io`` may be unique to your project, it does not include a project-specific identifier. This may cause issues if another project creates ``io.github.Foo-Bar`` which should be its own namespace but areas of ``flatpak`` may treat them @@ -221,11 +221,16 @@ For example, GNOME Dictionary will store user-specific data in:: ~/.var/app/org.gnome.Dictionary/data/gnome-dictionary -Note that applications can be configured to use non-default base directory -locations (see :doc:`sandbox-permissions`). +These environment variables are always set by flatpak and override any host values. +However if using the host directories are needed the ``$HOST_XDG_CONFIG_HOME``, +``$HOST_XDG_DATA_HOME``, ``$HOST_XDG_CACHE_HOME``, and ``$HOST_XDG_STATE_HOME`` environment +variables will be set if a custom value was set on the host. -Note that ``$XDG_STATE_HOME`` is only supported by Flatpak 1.13 and later. If -your app needs to work on earlier versions of Flatpak, you can use the +Note that ``$XDG_STATE_HOME`` and ``$HOST_XDG_STATE_HOME`` is only supported by Flatpak 1.13 +and later. If your app needs to work on earlier versions of Flatpak, you can use the ``--persist=.local/state`` and ``--unset-env=XDG_STATE_HOME`` finish args so the app will use the correct directory, even after Flatpak is later upgraded to >1.13. + +Note that applications can be configured to use non-default base directory +locations (see :doc:`sandbox-permissions`).