Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2025-08-05 21:24:15 -04:00
Code Issues Projects Releases Packages Wiki Activity

App menu troubleshooting: Use correct references and markup

Browse source 
Only markup edits, use `:file:`, `:guilabel:`, etc. And add full prompt.
This commit is contained in:
parulin 2025-07-27 07:47:06 -04:00
parent ba609d123e
commit bac93bcb1d
No known key found for this signature in database
GPG key ID: BC3830B42F4BF1F5
1 changed files with 41 additions and 37 deletions
Download patch file Download diff file Expand all files Collapse all files

78
user/troubleshooting/app-menu-shortcut-troubleshooting.rst
View file

@ -7,6 +7,8 @@ For ease of use Qubes aggregates shortcuts to applications that are installed in
|image1|
.. _how-to-add-a-shortcut:
How-to add a shortcut
---------------------
@ -15,11 +17,11 @@ With the graphical user interface
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To make applications newly installed show up in the menu, you can use the qube’s *Settings*. Under the *Applications* tab, use the *Refresh Applications* button. Linux qubes do this automatically, if the *Settings* are opened after the installation of the package.
To make applications newly installed show up in the menu, you can use the qube’s *Settings*. Under the :guilabel:`Applications` tab, use the :guilabel:`Refresh Applications` button. Linux qubes do this automatically, if the *Settings* are opened after the installation of the package.
|image2|
After that, use the directional buttons (``>``, ``>>``, ``<`` or ``<<``) to customize which applications are shown, by moving them to the *Applications shown in App Menu* part (on the right side). Use the *Apply* (or *Ok*) button to see the changes in the app menu.
After that, use the directional buttons (:guilabel:`>`, :guilabel:`>>`, :guilabel:`<` or :guilabel:`<<`) to customize which applications are shown, by moving them to the *Applications shown in App Menu* part (on the right side). Use the :guilabel:`Apply` (or :guilabel:`Ok`) button to see the changes in the app menu.
With the command-line interface
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -27,32 +29,32 @@ With the command-line interface
To update the list of available applications, use the ``qvm-sync-appmenus`` command in dom0, replacing ``<QUBE_NAME>`` by the qube name:
.. code:: bash
.. code:: console
$ qvm-sync-appmenus <QUBE_NAME>
[user@dom0] $ qvm-sync-appmenus <QUBE_NAME>
When using the *Refresh Applications* button in a qube’s settings, the command ``qvm-sync-appmenus`` is used at least one time. When refreshing an AppVM application, it is also run against the template. So the console equivalent of clicking the *Refresh button* is the following (always in dom0):
When using the :guilabel:`Refresh Applications` button in a qube’s settings, the command ``qvm-sync-appmenus`` is used at least one time. When refreshing an AppVM application, it is also run against the template. So the console equivalent of clicking the :guilabel:`Refresh Applications` button is the following (always in dom0):
.. code:: bash
.. code:: console
$ qvm-sync-appmenus <APPVM_NAME>
$ qvm-sync-appmenus <TEMPLATE_NAME>
[user@dom0] $ qvm-sync-appmenus <APPVM_NAME>
[user@dom0] $ qvm-sync-appmenus <TEMPLATE_NAME>
In dom0, the ``qvm-appmenus`` tool allows the user to see the list of available applications (unstable feature), the whitelist of currently show application (unstable feature) and to change this list:
.. code:: bash
.. code:: console
$ qvm-appmenus --set-whitelist <FILE_PATH> <QUBE_NAME>
[user@dom0] $ qvm-appmenus --set-whitelist <FILE_PATH> <QUBE_NAME>
To change the whitelist shown in app menu, you need to provide a list of the desktop entries. Each line contains a desktop entry name, with its ``.desktop`` extension, like this:
.. code:: bash
:
.. code::
qubes-open-file-manager.desktop
qubes-run-terminal.desktop
@ -76,9 +78,9 @@ You can manually create new entries in the “available applications” list of
1. Open a terminal window to the template.
2. Create a custom ``.desktop`` file in ``/usr/share/applications`` (you may need to first create the subdirectory). Look in ``/usr/share/applications`` for existing examples, or see the full `file specification <https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html>`__. It will be something like:
2. Create a custom ``.desktop`` file in :file:`/usr/share/applications` (you may need to first create the subdirectory). Look in :file:`/usr/share/applications` for existing examples, or see the full `.desktop file format`_ specification. It will be something like:
.. code:: bash
.. code:: desktop
[Desktop Entry]
Type=Application
@ -87,7 +89,7 @@ You can manually create new entries in the “available applications” list of
3. Follow the instructions in `How-to add a shortcut <#how-to-add-a-shortcut>`__
3. Follow the instructions in :ref:`how-to-add-a-shortcut`
@ -95,9 +97,9 @@ If you only want to create a shortcut for a single app qube:
1. Open a terminal window to the template.
2. Create a custom ``.desktop`` file in either ``~/.local/share/applications`` or ``/usr/local/share/applications`` (you may need to first create the subdirectory). See the previous instructions about the desktop entry format.
2. Create a custom ``.desktop`` file in either :file:`~/.local/share/applications` or :file:`/usr/local/share/applications` (you may need to first create the subdirectory). See the previous instructions about the desktop entry format.
3. Follow the instructions in `How-to add a shortcut <#how-to-add-a-shortcut>`__
3. Follow the instructions in :ref:`how-to-add-a-shortcut`
@ -105,13 +107,13 @@ To add a custom menu entry instead:
1. Open a terminal window to Dom0.
2. Create a custom ``.desktop`` file in ``~/.local/share/applications``. Look in the same directory for existing examples, or see the full `file specification <https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html>`__. You may use ``qvm-run`` inside the ``.desktop`` file; see :ref:`Behind the scenes <user/troubleshooting/app-menu-shortcut-troubleshooting:behind the scenes>` for more details.
2. Create a custom ``.desktop`` file in :file:`~/.local/share/applications`. Look in the same directory for existing examples, or see the full `file specification <https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html>`__. You may use ``qvm-run`` inside the ``.desktop`` file; see :ref:`Behind the scenes <user/troubleshooting/app-menu-shortcut-troubleshooting:behind the scenes>` for more details.
3. Edit the ``~/.config/menus/applications-merged/<vmname>-vm.menu`` file for the app qube.
3. Edit the :file:`~/.config/menus/applications-merged/{<vmname>}-vm.menu` file for the app qube.
4. Add a custom menu entry referring to your newly created ``.desktop`` file.
.. code:: bash
.. code:: xml
<Menu>
<Name>Webmail</Name>
@ -132,11 +134,11 @@ If you created a desktop entry but it doesn’t show up, there are some steps to
1. make sure the name is a valid name (only ASCII letters, numbers, hyphens and point)
2. if this program is available, run ``desktop-file-validate <DESKTOP_FILE_PATH>``
2. if this program is available, run :samp:`desktop-file-validate {<DESKTOP_FILE_PATH>}`
3. run it through ``gtk-launch``
4. run ``/etc/qubes-rpc/qubes.GetAppmenus`` and check that your desktop entry is listed in the output
4. run :file:`/etc/qubes-rpc/qubes.GetAppmenus` and check that your desktop entry is listed in the output
@ -152,33 +154,33 @@ What if a removed application is still in the app menu?
First, try this in dom0:
.. code:: bash
.. code:: console
$ qvm-appmenus --update --force <QUBE_NAME>
[user@dom0] $ qvm-appmenus --update --force <QUBE_NAME>
You can also try:
.. code:: bash
.. code:: console
$ qvm-appmenus --remove <QUBE_NAME>
[user@dom0] $ qvm-appmenus --remove <QUBE_NAME>
If that doesn’t work, you can manually modify the files in ``~/.local/share/applications/`` or in ``~/.local/share/qubes-appmenus/<QUBE_NAME>``.
If that doesn’t work, you can manually modify the files in :file:`~/.local/share/applications/` or in :file:`~/.local/share/qubes-appmenus/{<QUBE_NAME>}`.
For example, suppose you’ve deleted ``my-old-vm``, but there is a leftover Application Menu shortcut, and you find a related file in ``~/.local/share/applications/``, try to delete it. The hyphens in the name of the qube are replaced by an underscore and the letter, so instead of looking for ``my-old-vm``, try ``my_dold_dvm``.
For example, suppose you’ve deleted ``my-old-vm``, but there is a leftover Application Menu shortcut, and you find a related file in :file:`~/.local/share/applications/`, try to delete it. The hyphens in the name of the qube are replaced by an underscore and the letter, so instead of looking for ``my-old-vm``, try ``my_dold_dvm``.
What if my application is shown in app menu, but doesn't run anything?
----------------------------------------------------------------------
First, check in the corresponding ``.desktop`` file in ``~/.local/share/qubes-appmenus/<QUBE_NAME>/``, inside dom0.
First, check in the corresponding ``.desktop`` file in :file:`~/.local/share/qubes-appmenus/{<QUBE_NAME>}/`, inside dom0.
The line starting with ``Exec=`` points out the exact command run by dom0 to start the application. It should be something like:
.. code:: bash
.. code:: desktop
Exec=qvm-run -q -a --service -- <QUBE_NAME> qubes.StartApp+<APPLICATION_NAME>
@ -186,9 +188,9 @@ The line starting with ``Exec=`` points out the exact command run by dom0 to sta
It’s possible to run the command to check the output, by copying this line without ``Exec=``, and remove ``-q`` (quiet option). But it could be more useful to run it in the qube, with the ``qubes.StartApp`` service:
.. code:: bash
.. code:: console
$ /etc/qubes-rpc/qubes.StartApp <APPLICATION_NAME>
[user@any-qube] $ /etc/qubes-rpc/qubes.StartApp <APPLICATION_NAME>
@ -198,9 +200,9 @@ Behind the scenes
``qvm-sync-appmenus`` works by invoking the *GetAppMenus* :doc:`Qubes service </developer/services/qrexec>` in the target domain. This service enumerates applications installed in that qube and sends formatted info back to dom0 which creates ``.desktop`` files in the app qube/template directory of dom0.
For Linux qubes the service script is in ``/etc/qubes-rpc/qubes.GetAppMenus``. In Windows it’s a PowerShell script located in ``c:\Program Files\Invisible Things Lab\Qubes OS Windows Tools\qubes-rpc-services\get-appmenus.ps1`` by default.
For Linux qubes the service script is in :file:`/etc/qubes-rpc/qubes.GetAppMenus``. In Windows it’s a PowerShell script located in :file:`c:\Program Files\Invisible Things Lab\Qubes OS Windows Tools\qubes-rpc-services\get-appmenus.ps1` by default.
The list of installed applications for each app qube is stored in dom0’s ``~/.local/share/qubes-appmenus/<QUBE_NAME>/apps.templates``. Each menu entry is a file that follows the `.desktop file format <https://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html>`__ with some wildcards (*%VMNAME%*, *%VMDIR%*). Applications selected to appear in the menu are stored in ``~/.local/share/qubes-appmenus/<QUBE_NAME>/apps`` and in ``~/.local/share/applications/``.
The list of installed applications for each app qube is stored in dom0’s :file:`~/.local/share/qubes-appmenus/{<QUBE_NAME>}/apps.templates`. Each menu entry is a file that follows the `.desktop file format`_ with some wildcards (``%VMNAME%``, ``%VMDIR%``). Applications selected to appear in the menu are stored in :file:`~/.local/share/qubes-appmenus/{<QUBE_NAME>}/apps` and in :file:`~/.local/share/applications/`.
The whitelist given to ``qvm-appmenu --set-whitelist`` is stored as a feature called ``menu-items``, where each desktop entry is separated by a space.
@ -221,12 +223,14 @@ Note that you can create a shortcut that points to a ``.desktop`` file in your a
While this works well for standard applications, creating a menu entry for Windows applications running under *wine* may need an additional step in order to establish the necessary environment in *wine*. Installing software under *wine* will create the needed ``.desktop`` file in the target Linux qube in the directory ``~/.local/share/applications/wine/Programs/`` or a subdirectory thereof, depending on the Windows menu structure seen under *wine*. If the name of this file contains spaces, it will not be found, because the ``qvm-run`` command is falsely seen as terminating at this space. The solution is to remove these spaces by renaming the ``.desktop`` file accordingly, e.g. by renaming ``Microsoft Excel.desktop`` to ``Excel.desktop``. Refreshing the menu structure will then build working menu entries.
While this works well for standard applications, creating a menu entry for Windows applications running under *wine* may need an additional step in order to establish the necessary environment in *wine*. Installing software under *wine* will create the needed ``.desktop`` file in the target Linux qube in the directory :file:`~/.local/share/applications/wine/Programs/` or a subdirectory thereof, depending on the Windows menu structure seen under *wine*. If the name of this file contains spaces, it will not be found, because the ``qvm-run`` command is falsely seen as terminating at this space. The solution is to remove these spaces by renaming the ``.desktop`` file accordingly, e.g. by renaming :file:`Microsoft Excel.desktop` to :file:`Excel.desktop`. Refreshing the menu structure will then build working menu entries.
**Note:** Applications installed under *wine* are installed in AppVMs, not in the template on which these AppVMs are based, as the file structure used by *wine* is stored under ``~/.wine``, which is part of the persistent data of the AppVM and not inherited from its template.
**Note:** Applications installed under *wine* are installed in AppVMs, not in the template on which these AppVMs are based, as the file structure used by *wine* is stored under :file:`~/.wine`, which is part of the persistent data of the AppVM and not inherited from its template.
.. |image1| image:: /attachment/doc/r4.0-dom0-menu.png
.. |image2| image:: /attachment/doc/r4.0-dom0-appmenu-select.png
.. _.desktop file format: https://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html