spmenu-wiki/pages/Getting Started.md

Getting Started

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.

Supported operating systems

This is not some arbitrary requirement. While it may run if it's not listed here, I will not be providing support due to having a lack of experience with said operating system. The main operating systems that do not support speedwm are macOS and Microsoft Windows. UNIX like operating systems are the most likely to run it.

• Nearly all GNU/Linux distributions
  • NixOS and GNU Guix may require separate instructions. I will not provide support for these, use the existing documentation to set it up. Chances are if you use one of these you already know how to compile software for it.
• FreeBSD, OpenBSD, NetBSD
  • There are likely more BSDs that can run speedwm, but I cannot support all of them. Try it and see if it works.
• macOS/Mac OS X
  • macOS should be supported, however it requires Xquartz to be installed on the system. See Using spmenu on macOS for more information.

Installation on Gentoo GNU/Linux

Gentoo has slightly different instructions for setting up spmenu. While you can follow along with the generic installation instructions, I have a Gentoo overlay with packages for most if not all spmenu versions.

To get started, add my overlay. Then simply emerge x11-misc/spmenu.

If you want to install spmenu using Git, do this by adding the following lines:

=x11-misc/spmenu-9999 **

to /etc/portage/package.accept_keywords and then emerging the packages as per the instructions above.

Installation on generic GNU/Linux distributions

Installing spmenu on most GNU/Linux distributions is very simple. First, determine if you want to install it using Git (the absolute latest version) or using a stable tarball.

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.

While the list of dependencies will vary depending on the spmenu version you're going to install (see README.md for your specific version), below is a list for the latest release, 1.0.

• libX11
• libXrender
• freetype
• imlib2
  • Used for image support, can be disabled if you don't want this by:
    • build.sh: Setting imlib2=false in buildconf.
    • Makefile: Editing toggle.mk and commenting out a few lines.
• libXinerama
  • Can be disabled if you don't want/need multi-monitor support by:
    • build.sh: Setting xinerama=false in buildconf.
    • Makefile: Editing toggle.mk and commenting out a few lines.
• tcc compiler
  • You can swap it out for GCC or any other C99 compatible compiler by:
    • Makefile: Passing CC="gcc" to the make command.
    • build.sh: Adding CC="gcc" to the buildconf. command if you want)
• OpenSSL
  • Used to calculate MD5 of images if image support is enabled, can be disabled if you don't want this by:
    • build.sh: Setting imlib2=false and openssl=false in buildconf.
    • Makefile: Editing toggle.mk and commenting out a few lines.
• Pango
  • Can be disabled if you don't want/need Pango markup by:
    • build.sh: Setting pango=false and pangoxft=false in buildconf.
    • Makefile: Editing toggle.mk and commenting out a few lines.
• libconfig
  • Can be disabled if you don't want/need config file support by:
    • build.sh: Setting libconfig=false in buildconf.
    • Makefile: Editing toggle.mk and commenting out a few lines.

Installation using git

This assumes you have git installed.

cd into a location where your normal user (not root) has permission to both read and write. Do not clone the speedwm repository in ~/.config as speedwm will write configuration files to that location.

From here on, we're going to assume you are in the location ~/Documents. Run git clone https://git.speedie.site/spmenu spmenu to clone the repository into a directory named spmenu. Provided the repository hasn't moved and you have a working internet connection, you should have received a copy of the spmenu source code.

You can now cd spmenu into it so we can actually install it. If you need to make changes to the source code for whatever reason, now you want to do that.

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'.

Installation using a tarball

Installation using a tarball works pretty much the same. Visit the releases page and get the latest (or an old if you want) tarball.

cd into a location where your normal user (not root) has permission to both read and write.

Now we need to unpack the tarball and get our source code. To do this, you can use the tar command. I will spare you the time reading the man page and the command to unpack the tarball is tar -xpvf /path/to/the/spmenu/tarball.tar.gz. The -x argument here means extract. -p means preserve permissions. The -v means verbose, we want to see what's going on. -f means file, we want to specify a file to unpack.

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.