spmenu is an X11 menu application based on dmenu which takes standard input, parses it, and lets the user choose an option and sends the selected option to standard output. Options are separated by newlines.
In addition to this, it also serves as a run launcher through the included shell script spmenu_run which supports running binaries from $PATH but also file management and .desktop entries.
At as basic level, it takes standard input, and the selected option is output to standard output. This allows it to be extremely extensible, and I'm sure you can think of many use cases just by reading this. But that's not what we're going to start with.
While using a tarball can sometimes be more stable, it's not going to have any bug fixes or features I'm adding. With Git, issues can be fixed rather often. For this reason, it is recommended that you `git clone` the repository. If you do not have `git`, install it using your
distribution's package manager. If you're going to be using a 'stable' tarball, you do not need to install `git`.
this should be very, very easy and quick. Run `./build.sh` to install spmenu. The binary will be in `/usr/bin/spmenu` if PREFIX wasn't changed. If you need to use a
different compiler (tcc in Arch repositories has a few issues), you can set the compiler to use in the `buildconf`. The `buildconf` file is loaded by the build script and allows you to set various options. By default the buildconf is identical to what is used to build the Arch packages.
After unpacking it, there should be one directory; `spmenu-<version>`. Let's
`cd spmenu-<version>` into it. Now it's time to compile spmenu!
Now, it's time to compile it! Provided you have all dependencies installed,
this should be very, very easy and quick. Run `./build.sh` to install spmenu. The binary will be in `/usr/bin/spmenu` if PREFIX wasn't changed. If you need to use a
different compiler (tcc in Arch repositories has a few issues), you can set the compiler to use in the `buildconf`. The `buildconf` file is loaded by the build script and allows you to set various options. By default the buildconf is identical to what is used to build the Arch packages.
Now follow along with 'Using spmenu'.
### Using spmenu
spmenu accepts standard input. All of spmenu's features **require** standard input to be passed. If you only want to return the input text, you can simply pass nothing to spmenu and a blank menu will open up. The `spmenu_run` script bundled with spmenu which works as a run launcher uses this fact to list out all available executables which are then run. See the article [[Using spmenu as a run launcher]] for more information, this article **only** focuses on spmenu itself.
For example, `printf "Apple\nBanana\nOrange\n" | spmenu` will bring up a basic menu listing with three options, Apple, Banana and Orange. The one the user selects will be returned when (by default) Enter is pressed. You can also press Shift+Enter to select what you have typed in rather than the selected match.
spmenu also has a lot of arguments you can give. `spmenu --help` or if you prefer, `spmenu -h` will return a full list of available arguments. This is not the *only* way to configure spmenu, however it's useful when you want a setting to be applied only to the current instance. Most options are configurable through arguments, but not all of them are.
spmenu also has a config file through libconfig. A default config should be installed at `/usr/share/spmenu/spmenu.conf`. You can copy this to `~/.config/spmenu/spmenu.conf`. You may edit this file using your favorite text editor. Note that .Xresources takes priority over spmenu.conf configuration, as long as `xresources = 1`. You can find a list of accepted .Xresources values in `/usr/share/spmenu/example.Xresources`, and this file should more or less be identical to the defaults. For more information regarding the configuration file, see [[Configuring spmenu]].
Great, you should now know how spmenu works on a basic level. Now, if you are a tiling window manager user or just want a better run launcher, you can check out the article 'Using spmenu as a run launcher'. Alternatively, if you want to use this for scripting you can check out [[Scripting with spmenu]]. There are also many scripts that use spmenu to display items, see [[User scripts]] for that.