NimLaunch (SDL3)

NimLaunch is a keyboard-first launcher for Wayland and X11 built on SDL3. It covers three main workflows:

• application launching from .desktop entries
• configurable command/url/file shortcuts
• generic stdin-driven selection through --dmenu

It uses SDL3 for native Wayland/X11 support with GPU-backed compositing and loads PNG/SVG icons through the SDL3 stack.

Features

• Fuzzy app search with typo tolerance, recent-item bias, and persistent usage-based ranking.
• Desktop entry actions for apps that expose secondary launch actions.
• Prefix commands: :t, :c, :s, :r, !, and custom groups.
• Vim mode (optional): j/k navigation, / : ! command bar, gg/G, :q, etc.
• Themes with live preview, status/toast messages, and clock overlay.
• --dmenu mode for scripts, and other stdin-driven workflows.
• Icons from .desktop files (PNG/SVG) with theme-aware lookup; can be disabled.
• Window opacity setting (0.1–1.0) via SDL3 when supported.

Documentation

• Configuration Guide
• Themes
• Groups and Shortcuts
• Dmenu Mode

Install

Grab a compiled binary from the releases page.

Build

Note

Runtime/build deps: nim >= 2.0, sdl3, sdl3-ttf, sdl3-image, plus a font (default ttf-dejavu).

Nim package note: the Nim SDL3 and parsetoml sources are vendored in packages/, so Nimble does not need to download those wrappers separately.

Optional helpers:

• fd and/or locate for faster :s file search

Archlinux

sudo pacman -S sdl3 sdl3-ttf sdl3-image ttf-dejavu --needed

Ubuntu

sudo apt install libsdl3-dev libsdl3-ttf-dev libsdl3-image-dev fonts-dejavu-core

OpenSUSE

# Tumbleweed / Slowroll package names:
sudo zypper install SDL3-devel SDL3_ttf-devel SDL3_image-devel dejavu-fonts

If you are on Leap and a name differs, run zypper search sdl3 to find the matching package variant.

Solus

sudo eopkg it sdl3-devel sdl3-ttf-devel sdl3-image

Build from source

git clone https://codeberg.org/Vyrnexis/NimLaunch.git
cd NimLaunch

nimble build          # package/default build -> ./nimlaunch
nimble -y nimDebug    # debug build -> ./bin/nimlaunch
nimble -y nimRelease  # release build for current CPU (fastest on this machine) -> ./bin/nimlaunch
nimble -y nimPortable  # portable + smaller release build (generic x86_64 baseline) -> ./bin/nimlaunch

For a more portable release build (via Zig/clang), use:

nimble -y zigDebug    # debug build -> ./bin/nimlaunch
nimble -y zigRelease  # release build for current CPU via Zig/clang -> ./bin/nimlaunch
nimble -y zigPortable  # portable + smaller Zig/clang release build (generic x86_64 baseline) -> ./bin/nimlaunch

Use nimble c from project root if you need custom compiler flags:

nimble c -d:release --opt:speed -o:./bin/nimlaunch src/nimlaunch.nim

./nimlaunch
./bin/nimlaunch

Place the binary (nimlaunch) somewhere on your PATH (e.g., ~/.local/bin) and bind a hotkey to launch it. The TOML config is auto-generated on first run.

Wayland/X11

Runs natively on both via SDL3 (no XWayland required on Wayland). Borderless window like the original. GPU compositing handles fills/icons/text blits; SDL_ttf still rasterizes glyphs in software.

Troubleshooting

• Build fails with cannot open .../src/nimlaunch.nim: build from project root, and use nimble build, nimble c ..., or the provided Nimble tasks.
• Build fails with cannot open file: sdl3 or parsetoml: make sure you are building from project root so config.nims can add the vendored packages/ paths.
• nimble nimPortable or nimble zigPortable is unknown: update to the current .nimble file.
• :s search feels slow: install fd and/or locate so search avoids the slower $HOME fallback walk.
• Icons are missing for SVG apps: ensure your SDL3_image build includes SVG support. This project now loads SVG icons through SDL3_image directly.
• --dmenu looks empty: make sure you are piping newline-separated input into it, for example printf "one\\ntwo\\n" | nimlaunch --dmenu.
• Text looks wrong or too small: set [font].fontname to an installed font and size (e.g., "Dejavu:size=16").
• Wayland/Niri black padding or delayed repaint: build with nimble c -d:nimlaunchWindowDebug --nimcache:/tmp/nimlaunch_dbg_cache -o:/tmp/nimlaunch_dbg src/nimlaunch.nim and run /tmp/nimlaunch_dbg to log window events + redraw timing.
• Theme changes do not persist: verify ~/.config/nimlaunch/nimlaunch.toml is writable.

Dmenu Mode

--dmenu turns NimLaunch into a generic selector for stdin-provided items.

Example:

printf "one\ntwo\nthree\n" | ./nimlaunch --dmenu

Behavior:

• Enter prints the selected line and exits with status 0
• Esc cancels and exits with status 1
• empty query preserves the original input order

See Dmenu Mode for real use cases, wrapper patterns, and the included audio sink example.

Quick Reference

Core controls:

Trigger	Context	Effect
Type text	Normal	Fuzzy-search applications; top hit updates instantly
Enter	Normal or command bar	Launch the highlighted entry immediately
Esc	Command bar	Close the bar, keep the narrowed results selected
Esc	Normal	Exit NimLaunch
↑ / ↓ / PgUp / PgDn / Home / End	Any	Navigate the results list
/	Normal	Toggle the command bar (restores previous / search)
: / !	Normal	Open the bar primed for a prefix or ! command
Ctrl+U	Command bar	Clear the current query
Ctrl+H / Backspace	Command bar	Delete one character (closes the bar when empty)

Built-in prefixes

Prefix	Example	Description
none	fire	Regular app search; rankings favour prefixes, recent launches, and persistent usage
:t	:t nord	Browse themes; Up/Down preview, Enter to keep selection
:s	:s notes	Search files (fd → locate → bounded $HOME walk)
:c	:c sway	Match files inside ~/.config and open with the default handler
:r	:r htop	Run a shell command inside your preferred terminal
!	!htop	Shorthand for :r without the colon
:<group>	:sys lock	Run grouped shortcuts (for example a sys group for session/power actions)

Configuration

Config path: ~/.config/nimlaunch/nimlaunch.toml (auto-generated on first run).

The checked-in example config is a public sample config.

For the full config layout, field descriptions, theme handling, and generated default behavior, see Configuration Guide.

More Detail

• Shortcut and group configuration: Groups and Shortcuts
• Theme definition and persistence: Themes
• --dmenu wrappers and patterns: Dmenu Mode