DESKTOP.ECLASS

Section: eclass-manpages (5)
Updated: Feb 2026
Index Return to Main Contents

NAME

desktop.eclass - support for desktop files, menus, and icons

SUPPORTED EAPIS

7 8 9

FUNCTIONS

make_desktop_entry [--eapi9] <command> [options]

Make a .desktop file and install it in /usr/share/applications/.

--eapi9:    Switch to getopts style arguments instead of order based
            As the naming implies, this is off by default for EAPI=[78],
            but mandated by future EAPI.
command:    Exec command the app is being run with, also base for TryExec
---         Options:
name:       Name that will show up in the menu; defaults to PN
            with --eapi9: must not contain arguments, use --args for that
icon:       Icon to use with the menu entry; defaults to PN
            this can be relative (to /usr/share/pixmaps) or
            a full path to an icon
categories: Categories for this kind of application. Examples:
            https://specifications.freedesktop.org/menu-spec/latest/apa.html
            if unset, function tries to guess from package's category
entry:      Key=Value entry to append to the desktop file;
            with --eapi9: multiple allowed; old style: a printf string
---         Additional parameters available using --eapi9:
args:       Arguments (binary params and desktop spec field codes) to add
            to Exec value, separated by a space if multiple
desktopid:  <desktopid>.desktop will be created. Must be same as "app id"
            defined in code (including reverse qualified domain if set);
            defaults to <command>
comment:    Comment (menu entry tooltip), defaults to DESCRIPTION
force:      Force-write resulting desktop file (overwrite existing)

Example usage:

Deprecated, in order:
  <command> [name] [icon] [categories] [entries...]
New style:
  --eapi9 <command> [-a args] [-d desktopid] [-C comment] [-i icon]
  --eapi9 <command> [-n name] [-e entry...] [-c categories]

make_session_desktop [--eapi9] <command> [options]

Make a session file to start a Wayland compositor or X window manager and install it in the appropriate location.

--eapi9:   Switch to getopts style arguments instead of order based
           As the naming implies, this is off by default for EAPI=[78],
           but mandated by future EAPI.
command:   Exec command the session is being started with, also base
           for TryExec
           with --eapi9: must not contain arguments, use --args for that
---        Options:
name:      Name that will be displayed in login managers;
           with --eapi9: defaults to PN
---        Additional parameters available using --eapi9:
args:      Arguments (binary params) to add to Exec value, separated by
           space if multiple
entry:     Key=Value entry to append to the session desktop file;
           multiple allowed
comment:   Comment, defaults to generic text
filename:  <filename>.desktop will be created. defaults to <command>
xsession:  Create an XSession file (Type=XSession) and install into
           /usr/share/xsessions/
           default is wayland session into /usr/share/wayland-sessions

Example usage:

Deprecated, in order:
  <name> <command> [command args...]
  You can set the file name of the session via the ${wm} variable.
New style:
  --eapi9 <command> [-a args] [-f filename] [-C comment]
  --eapi9 <command> [-n name] [-e entry...] [-X]

domenu <menus>

Install the list of .desktop menu files into the appropriate directory (/usr/share/applications).

newmenu <menu> <newname>

Like all other new* functions, install the specified menu as newname.

doicon [options] <icons>

Install icon into the icon directory /usr/share/icons or into /usr/share/pixmaps if "--size" is not set. This is useful in conjunction with creating desktop/menu files.

 options:
 -s, --size
   !!! must specify to install into /usr/share/icons/... !!!
   size of the icon, like 48 or 48x48
   supported icon sizes are:
   16 22 24 32 36 48 64 72 96 128 192 256 512 1024 scalable
 -c, --context
   defaults to "apps"
 -t, --theme
   defaults to "hicolor"

icons: list of icons

example 1: doicon foobar.png fuqbar.svg suckbar.png
results in: insinto /usr/share/pixmaps
            doins foobar.png fuqbar.svg suckbar.png

example 2: doicon -s 48 foobar.png fuqbar.png blobbar.png
results in: insinto /usr/share/icons/hicolor/48x48/apps
            doins foobar.png fuqbar.png blobbar.png

newicon [options] <icon> <newname>

Like doicon, install the specified icon as newname.

example 1: newicon foobar.png NEWNAME.png
results in: insinto /usr/share/pixmaps
            newins foobar.png NEWNAME.png

example 2: newicon -s 48 foobar.png NEWNAME.png
results in: insinto /usr/share/icons/hicolor/48x48/apps
            newins foobar.png NEWNAME.png

ECLASS VARIABLES

_DESKTOP_IDS = (): Internal array containing any app-ids used by make_desktop_entry() calls. Lets us keep track of/avoid duplicate desktop file names.

MAINTAINERS

base-system@gentoo.org

REPORTING BUGS

Please report bugs via https://bugs.gentoo.org/

FILES

desktop.eclass

This document was created by man2html, using the manual pages.
Time: 03:27:02 GMT, February 04, 2026