Blackbox Documentation/Blackbox Menus/System Integration

This page will attempt to describe methods of integrating the Blackbox main menu with various other menu systems you may have in use on your system.

Please keep in mind that this is a website about Blackbox. Do not get caught too much in describing the various menu systems for general use. Always come back to: "what does this do for Blackbox?"

1 Debian menu system

1.1 Description

1.2 Preparing the system

1.2.1 Debian, Ubuntu

1.2.2 ...other distros?...

1.2.3 Blackbox from source

1.3 Blackbox integration

2 PCLinuxOS?

3 Other systems?

1) Debian menu system

1.1) Description

The Debian menu system* has been developed for Debian, but it is currently used by a number of other Linux distributions as well. Please see its official manual* for detailed information covering more than just Blackbox.

This system combines three parts:

Each package that wants to be present in the menus provides one single file, describing the category, icon, label, command and so on for each menu entry it requires.
Each package which needs a menu system (desktop environments and window managers, usually) provides one single file (a method file), describing the format of its specific menus and a location for the auto-generated menu files.
The menu package provides the command update-menus, which combines the input (the package-provided menu entry descriptions) with the output (the menu formats) to produce constantly updated, auto-generated menus in all the needed formats. This command is run each time a package is added, removed or updated and will update the menus accordingly.

The system is particularly powerful because it distributes the workload among the package maintainers. It is trivial to add your package executables to the menus, it is trivial to add support for yet another menu system, and it is trivial to include the auto-generated menus in your personal main menu.

For now, the various other menu systems delegate the Debian auto-generated menus as a submenu of their own's, which is what Blackbox will do too (see below). Ie. nobody uses the Debian menu exclusively.

1.2) Preparing the system

The following lists contains information about known distributions which use the Debian menu system, with specific details.

Generally, if you use the Blackbox package provided by your distribution, then everything should already be set up and the auto-generated menu files for your distro should already exist.

1.2.1) Debian, Ubuntu

You must first install the menu* package.
Installing the blackbox binary package will set up everything for you, so you can stop here. Continue if you compile your own.
Method file is in /etc/menu-methods/blackbox and must be executable (run chmod a+x on it).
Possible manual update commands are:
- update-menus
- update-menus --menumethod /etc/menu-methods/blackbox
Auto-generated files:
- /etc/X11/blackbox/blackbox-menu
- ~/.blackbox/blackbox-menu.

1.2.2) ...other distros?...

FIXME: please add specific instructions for other distros that use this menu system.

1.2.3) Blackbox from source

If you compile your own Blackbox you can still use this system, provided it is available for your distro and you have installed it. If the answer is yes, then proceed as follows:

Download the binary Blackbox package for your distribution.
Extract the method file from it and place it in the appropriate directory, as specified above. Make sure it's executable (run chmod a+x on it).
Run one or several of the manual update commands listed for your distro, above. You should only have to do this by hand once, then the packaging system is supposed to start updating every time it installs or removes a package.
You should now have the auto-generated ...-menu files.

1.3) Blackbox integration

Once you obtain the ...-menu files, one way or another, you can simply edit your regular menu file and [include] one of them. Example:

[submenu] (Debian)
  [include] (~/.blackbox/blackbox-menu)
[end]

Now open your main menu and enjoy a constantly updated submenu filled with everything you have installed on your system.

2) PCLinuxOS?

PCLinuxOS* "just works" with blackbox's menus.

After blackbox is installed (via apt-get or synaptic), the default menu which blackbox sees is kept up-to-date automatically.

Blackbox may require restarting after using apt-get or synaptic to manage software.

3) Other systems?

Feel free to describe other methods of integrating the Blackbox menus with other menus. If you have one, add a heading above this one, and start expanding it. But always remember the purpose: how can Blackbox pick up the menus from other systems?