MENUFILE(5)

📦
version 2.1.51build1 · 2 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

okay bestie, we're doing the menufile page from the Debian File Formats Manual 💖 this is the one that explains how menu entries get into the Debian menu system, and it's genuinely iconic once it clicks, i promise.

🎀 NAME 🎀

menufile — an entry in the Debian menu system. that's it, that's the whole name section, periodt.

🌸 SYNOPSIS 🌸

~/.menu/*

/etc/menu/*

/usr/lib/menu/*

/usr/share/menu/*

/usr/share/menu/default/*

💅 DESCRIPTION 💅

Menu files are literally how you add entries to the Debian menu system. the system administrator can drop menu files into /etc/menu/ to override the menu files that packages put in /usr/share/menu/. and you, the user, can put menu files in ~/.menu/ to override all the other menu files. yes, everything. main character energy fr fr 👑

okay so, if you want the complete spec of menu files, read the Debian menu manual living at /usr/share/doc/menu/html. this page is the vibe summary, that's the full lore.

Menu files are usually named after the Debian package that contains the programs listed inside them. in a menu file you can list several "menu entries", each one specifying a specific item in the menu structure. every menu entry says which packages it depends on — and if that package isn't installed, the menu entry just gets ignored by update-menus(1). no drama, it just skips it. 🙈

tiny but crucial detail: inside a menu entry you can specify pseudo-packages that start with "local." — and update-menus will always use those menu entries. always always.

and if you want to remove an item from the menu entirely? make an empty menu file with the same name as the file you're trying to override. that's the move. that's the whole trick. 🍓

🦋 Examples 🦋

so Dosemu could install the following menu file as /usr/share/menu/dosemu:

 ?package(dosemu):needs="text" section="Applications/Emulators" \
title="Dosemu" command="dosemu"
 ?package(dosemu):needs="X11" section="Applications/Emulators" \
title="Dosemu" command="xdos"

now the system administrator wants to override this file to change how dosemu is run, so /etc/menu/dosemu gets created:

 ?package(dosemu):needs="text" section="Applications/Emulators" \
title="Dosemu" command="dosemu -A"
 ?package(dosemu):needs="X11"  section="Applications/Emulators" \
title="Dosemu" command="xdos -A"

but what if a user simply does not want Dosemu appearing in the menus at all? they create an empty file named ~/.menu/dosemu. gone. deleted. not in this house. 💀

✨ FORMAT ✨

a menu file is made of 0 or more lines that look exactly like this:

?package(package-name):var1=value1 var2=value2  ...

and here's what every variable means, bestie, read carefully:

  • needs — specifies what kind of environment the program requires. this variable must be defined, and it should be one of the following:
    • needs="text" — the program requires a terminal.
    • needs="x11" — the program requires an X server.
    • needs="vc" — the program requires a Linux console (i.e.: svgalib programs).
    • needs="wm" — the program is a window manager.
    • needs="fvwmmodule" — the program is a fvwm compatible module.
  • section — the section in which the menu entry should appear. peep MENU LAYOUT for the preferred section names 👀
  • icon — an icon for this menu entry. if no icon is available, just don't define this. simple as that.
  • title — the title of the program that will appear on the menus. keep it short!! and here's the fun part: if two menu entries share the same title and section, the one that best fits the available display will be used. so in the example above with two menu entries that both have the menu id "title", if X is available the X11 one will be used; otherwise the text one will be used. must be defined.
  • command — the command to be executed when this menu entry is selected.
  • hints — a comma-separated list of hints on how to group menu entries; see the manual.

the authoritative list of Debian's menu structure is maintained in the Debian Menu sub-policy document, which is part of the Debian Policy package. the menu structure below is included only for convenience. and listen:

please do not put your packages into any other sections. the list is the list, no cap. 🫶

use / to separate sub-menu names, for example, "Applications/Editors" or "Games/Arcade".

 Applications
   Accessibility
   Amateur Radio
   Data Management
   Editors
   Education
   Emulators
   File Management
   Graphics
   Mobile Devices
   Network
     Communication
     File Transfer
     Monitoring
     Web Browsing
     Web News
   Office
   Programming
   Project Management
   Science
     Astronomy
     Biology
     Chemistry
     Data Analysis
     Electronics
     Engineering
     Geoscience
     Mathematics
     Medicine
     Physics
     Social
   Shells
   Sound
   System
     Administration
     Hardware
     Language Environment
     Monitoring
     Package Management
     Security
   Terminal Emulators
   Text
   TV and Radio
   Viewers
   Video
   Web Development
 Games
   Action
   Adventure
   Blocks
   Board
   Card
   Puzzles
   Simulation
   Strategy
   Tools
   Toys
 Help
 Screen
   Saving
   Locking
 Window Managers
 FVWM Modules
 Window Maker

💖 NOTES 💖

if you want to specify an icon or hotkey for a sub-menu (for example, the Editors sub-menu), just use the same syntax but leave the command empty:

?package(mypackage):needs="X11" section="Applications" \
 icon="/usr/share/pixmaps/icon.xpm" hotkey="E" title="Editors"

and whenever any menu files are changed, you must run update-menus(1). must must must. it's not optional, bestie, it's the whole vibe check. ⭐

🧚 FILES 🧚

just so we're clear on the rules: earlier listed files override later files with the same names. earlier = stronger. 💪

  • ~/.menu/* — menu files added by the user.
  • /etc/menu/* — menu files added by the system administrator.
  • /usr/lib/menu/* — architecture-dependant menu files provided by other Debian packages.
  • /usr/share/menu/* — architecture-independant menu files provided by other Debian packages.
  • /usr/share/menu/default/* — menu files provided by the menu package.

👑 AUTHORS 👑

Joost Witteveen <joostje@debian.org>, based on work by Lars Wirzenius <liw@iki.fi>. now maintained by Bill Allombert <ballombe@debian.org>.

(man page by Joey Hess, <joeyh@debian.org>)

🌸 SEE ALSO 🌸

update-menus(1), /usr/share/doc/menu/html/index.html

and that's the whole page, bestie 🎀 mwah 💋 this lil manual page came to you from DEBIAN, filed under the File Formats Manual, and it lives at MENUFILE(5). go run update-menus and slay 💅✨

📦 where this page comes from