smenu: the readme warns about its own option parser
smenu started as a lightweight and flexible terminal menu generator, but quickly evolved into a powerful and versatile CLI selection tool for interactive or scripting use.
At a glance
- What is it?
- A terminal selection filter that reads words from standard input and draws a scrolling window at the cursor position without clearing the screen. Its build system ships both a generated configure script and a hand written one, its options come from a separate project the author warns about, and its right to left alignment bug is stated rather than hidden.
- Who is it for?
- Use smenu when you want to turn a stream of lines into a keyboard and mouse selection without pulling in a curses program of your own, and particularly as a control-R replacement in an interactive shell. Three things to know.
- Can I use it commercially?
- Yes, with conditions. MPL-2.0 is a weak copyleft licence: you can use it inside commercial and closed-source software, but if you distribute changes to its own files, you must publish those changes under the same licence.
- Is it still maintained?
- Yes. The repository last received commits 11 days ago.
- What is it written in?
- Mainly C, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- p-gen/smenu2,505 ★ · +11
| Repository | 2026-09-30 | 2026-11-15 |
|---|---|---|
| p-gen/smenu | 2.5k | 2.5k |
11 Stars in the last 46 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The tree ships configure and the docs tell you not to use it
The root contains a full set of autotools output: configure, configure.ac, Makefile.in, Makefile.am, aclocal.m4, config.h.in and a build-aux directory. It also contains a hand written shell script called build.sh. The build instructions point at the shell script, saying to use it, and add that it accepts the same arguments as the GNU configure script with build.sh --help to list them. So there are two ways in, one of them a generated file that would normally be treated as build output, and the documentation prefers the other. A related detail: Makefile.in is committed but no Makefile is, so a checkout is not buildable until one of the two entry points has run.
The author warns about his own option system
There is a section headed as a warning for versions after v0.9.15, and its content is unusual in a readme. Those versions use a new options system called ctxopt, which may contain bugs, and the request is to report them so they can be fixed in the next release of either smenu or ctxopt. The warning continues: command line arguments may also need to be rearranged in some cases because of the new option management system, followed by an apology for the extra work that might entail. ctxopt is a separate project by the same author, and the two files that implement it, ctxopt.c and ctxopt.h, are committed into this tree rather than pulled in as a dependency.
The window is drawn over the terminal and never erased
The central design statement is three sentences long. The screen is not cleared at the start and end of execution, the selection window is displayed at the cursor position, and the previous contents of the terminal are neither modified nor lost. That is what separates smenu from a full screen selector, and it is why the program can be dropped into a pipeline and disappear cleanly when you press Enter. The consequence is that the window stays on screen once the program ends unless something cleans it, and the readme notes you can add the -d parameter to instruct smenu to clean the selection window after selecting an entry. The layout options include multi-line windows: the Linux example passes a window split string built from a tab and a newline character.
Right to left alignment is a listed bug
The readme has a Bugs section, and it names one item: right-alignment of lines written in right to left languages, such as Farsi or Hebrew, is not respected. It is stated plainly, with no workaround and no version attached, which tells you it is a known limitation rather than a regression. The same theme continues into the encoding notes. UTF-8 is supported, including double-width characters, but the glyphs must already be in canonical form because no effort will be made to normalise them. So the program will render what it is given, and normalising input is the caller's problem.
Grapheme clusters are experimental and terminal dependent
Extended grapheme clusters are the second encoding caveat, and this one is qualified more heavily than the rest. The support is described as still experimental, and the readme says it works much better if appropriate terminals such as WezTerm or iTerm are used. That is a statement about the terminal rather than about the program: the readme also says smenu should work on all terminals managed in the terminfo database, which is a strong claim for a terminal program, and then narrows it for this one feature. Practical upshot is that if your data contains emoji sequences or combining marks, test the behaviour in the terminal you actually use before relying on it.
A full test run takes about twenty-one minutes
The testing section is apologetic about its own age, describing the included system as relatively young and asking readers to be indulgent. It also has dependencies, so the instructions point at a README inside the tests directory before going further. Running everything means executing a script named tests.sh from that directory and takes around twenty-one minutes. Failures are expected in places: on systems such as the BSDs some tests may fail, which the readme attributes to differences in posix and libc implementations, notably where specific regular expressions or uncommon UTF-8 byte sequences are involved. When a test fails for an unknown reason the request is to send the directory name and the corresponding .bad file, and new tests are written as a .in file and a .tst file.
Two places to report things, and the readme admits the confusion
There is a whole section on where to report things, and it opens by saying the author is aware there may be confusion about whether to use an issue or a discussion. Issues are for bugs and for feature requests that can be clearly described. Discussions are for questions, for not being sure how to achieve something, for an idea whose shape is not settled, for showing off something cool that was built with the program, and for anything else. Both links are spelled out at the top of the section. It is a small thing, but it is the kind of section that saves a maintainer time and it tells you what kind of project this is.
The source is split by concern and the documentation is reStructuredText
The file list reads like a small library rather than one program. Alongside the main smenu.c there are safe.c, ini.c, list.c, utf8.c, usage.c, index.c, fgetc.c for fast character input, xmalloc.c for allocation wrappers, and a header called tinybuf. Documentation lives in the tree too, in reStructuredText: a man page called smenu.1, an INTERNALS file for developers, a FAQ, a TODO, a ChangeLog and a COPYRIGHT file beside the MPL 2.0 licence header in the readme. A SUMMARY file at the root is the table of contents of that document set, and three example directories cover a menu of logical volume manager entries, the simple menu and a yes or no prompt. The release list runs 1.3.0, 1.4.0 and 1.5.0, with the last recorded push dated 2026-04-17.
Editorial conclusion
Use smenu when you want to turn a stream of lines into a keyboard and mouse selection without pulling in a curses program of your own, and particularly as a control-R replacement in an interactive shell. Three things to know. The build instructions point at a shell script rather than the configure script the repository also ships, and the arguments may be reordered in versions after v0.9.15 because of the option system the readme openly describes as possibly buggy. Grapheme cluster handling is experimental and terminal dependent. And right to left alignment is a documented bug rather than a fixed behaviour.
Frequently asked questions
How do I build smenu?
Use the provided build.sh script, which accepts the same arguments as GNU configure; type build.sh --help to see them. Once the build is complete, a make install with the appropriate privileges installs it. The tree also contains a generated configure script.
Does smenu clear the terminal when it exits?
No. The screen is not cleared at the start or end of execution, the selection window is drawn at the cursor position, and the previous terminal contents are neither modified nor lost. Adding the -d parameter makes it clean the window after an entry is selected.
What is ctxopt and why does smenu warn about it?
It is the new options system used by versions after v0.9.15. The README warns it may contain bugs and that command line arguments may need rearranging because of it, and asks for reports so they can be fixed in the next release of smenu or ctxopt.
What are the known bugs in smenu?
Right-alignment of lines written in right-to-left languages, such as Farsi or Hebrew, is not respected.
Does smenu handle UTF-8?
Yes, including double-width characters and extended grapheme clusters. Grapheme cluster support is still experimental and works much better in terminals such as WezTerm or iTerm, and glyphs must already be in canonical form because no normalisation is performed.
Where should I report a smenu bug?
Open an issue for bugs and for feature requests you can clearly describe. Open a discussion for questions, for being unsure how to achieve something, for ideas whose shape is unsettled, and for showing off what you built with it.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/p-gen-smenu)Star history chart for your README
[](https://hysenlabs.com/projects/p-gen-smenu)Was this useful?