From bac93bcb1da94c052c888b3feaefdba38e862719 Mon Sep 17 00:00:00 2001 From: parulin <161326115+parulin@users.noreply.github.com> Date: Sun, 27 Jul 2025 07:47:06 -0400 Subject: [PATCH] App menu troubleshooting: Use correct references and markup Only markup edits, use `:file:`, `:guilabel:`, etc. And add full prompt. --- .../app-menu-shortcut-troubleshooting.rst | 78 ++++++++++--------- 1 file changed, 41 insertions(+), 37 deletions(-) diff --git a/user/troubleshooting/app-menu-shortcut-troubleshooting.rst b/user/troubleshooting/app-menu-shortcut-troubleshooting.rst index a63e4c99..f3f51a73 100644 --- a/user/troubleshooting/app-menu-shortcut-troubleshooting.rst +++ b/user/troubleshooting/app-menu-shortcut-troubleshooting.rst @@ -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 ```` by the qube name: -.. code:: bash +.. code:: console - $ qvm-sync-appmenus + [user@dom0] $ qvm-sync-appmenus -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 - $ qvm-sync-appmenus + [user@dom0] $ qvm-sync-appmenus + [user@dom0] $ qvm-sync-appmenus 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 + [user@dom0] $ qvm-appmenus --set-whitelist 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 `__. 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 `__. You may use ``qvm-run`` inside the ``.desktop`` file; see :ref:`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 `__. You may use ``qvm-run`` inside the ``.desktop`` file; see :ref:`Behind the scenes ` for more details. -3. Edit the ``~/.config/menus/applications-merged/-vm.menu`` file for the app qube. +3. Edit the :file:`~/.config/menus/applications-merged/{}-vm.menu` file for the app qube. 4. Add a custom menu entry referring to your newly created ``.desktop`` file. - .. code:: bash + .. code:: xml Webmail @@ -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 `` +2. if this program is available, run :samp:`desktop-file-validate {}` 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 + [user@dom0] $ qvm-appmenus --update --force You can also try: -.. code:: bash +.. code:: console - $ qvm-appmenus --remove + [user@dom0] $ qvm-appmenus --remove -If that doesn’t work, you can manually modify the files in ``~/.local/share/applications/`` or in ``~/.local/share/qubes-appmenus/``. +If that doesn’t work, you can manually modify the files in :file:`~/.local/share/applications/` or in :file:`~/.local/share/qubes-appmenus/{}`. -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//``, inside dom0. +First, check in the corresponding ``.desktop`` file in :file:`~/.local/share/qubes-appmenus/{}/`, 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 -- qubes.StartApp+ @@ -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 + [user@any-qube] $ /etc/qubes-rpc/qubes.StartApp @@ -198,9 +200,9 @@ Behind the scenes ``qvm-sync-appmenus`` works by invoking the *GetAppMenus* :doc:`Qubes service ` 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//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 ``~/.local/share/qubes-appmenus//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/{}/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/{}/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 +