Anatomy of rc.lua
The default somewmrc.lua contains the theme, widgets, bindings, and rules for SomeWM 2.1. To edit your own copy, start with the basics tutorial.
At a glance
| Change | Config section |
|---|---|
| Colours, fonts, or theme | Theme system |
| Terminal, editor, or modifier key | Lockscreen and defaults |
| Available window layouts | Layouts |
| Background image or gradient | Wallpaper |
| Tags, clock, or bar widgets | Wibar |
| Keyboard shortcuts | Global or client bindings |
| Placement of particular applications | Rules |
| Focus on mouse entry | Sloppy focus |
1. Error handling
The request::display_error handler shows Lua errors through naughty.notification. The awesome.x11_fallback_info block reports detected X11-specific patterns. Detection alone does not skip the user config, which is still attempted.
2. Theme system
theme_name defaults to "gruvbox". If $XDG_CONFIG_HOME/somewm/theme exists, its contents select a theme from the installed themes directory. Without XDG_CONFIG_HOME, the path is ~/.config/somewm/theme.
switch_theme(name) saves the name and reloads the config. beautiful.init() loads its theme file. For a custom file, follow the theme tutorial.
3. Custom "s" logo
The Cairo block assigns a generated logo to beautiful.awesome_icon. The launcher uses this image. To use your own icon, replace the block with an assignment to an image path.
4. Lockscreen and defaults
require("lockscreen").init() creates the built-in lockscreen. The following local variables are used throughout the config:
| Variable | Default |
|---|---|
terminal | "foot" |
editor | $EDITOR, or "nano" |
editor_cmd | Terminal command with -e and the editor |
modkey | "Mod4", the Super key |
5. User customization examples
This section contains commented examples. Nothing runs until uncommented. For working configurations and their limits, see input devices, autostart, fractional scaling, and locking.
6. Menu
theme_menu lists the built-in themes. menu_items supplies the main menu, opened by the launcher, right-clicking the desktop, or Mod4 + w. menubar.utils.terminal selects the terminal used for text applications launched through the menubar.
7. Layouts
The request::default_layouts handler registers layouts in cycle order. tile is first and is the default for new tags. Reorder the list to change the default, or remove entries to shorten the cycle. See the layout reference and carousel tutorial.
8. Wallpaper
The request::wallpaper handler uses awful.wallpaper with the first matching option:
beautiful.wallpaper_colors: gradient and centred logo.beautiful.wallpaper: image.beautiful.bg_normal: solid colour, falling back to"#222222".
Unset wallpaper_colors to use an image with a theme that defines a gradient.
9. Tag persistence
awful.permissions.tag_screen saves tag state when a monitor disconnects. The commented disconnect_signal call disables saving. Restoration happens in the next section. See tag persistence.
10. Wibar
mytextclock is created before the per-screen handler. Inside request::desktop_decoration, the config restores saved tags or creates dev, web, chat, files, and media. It then creates the prompt, layoutbox, taglist, tasklist, and s.mywibox.
The bar uses align.horizontal with expand = "none" to centre the clock across the screen. The tasklist belongs to the left group, alongside the launcher, tags, and prompt. The right group contains the tray and layoutbox.
When changing the bar, keep the tag restore/create block. The wibar tutorial identifies the part to replace. The widgets tutorial replaces the clock.
11. Root mouse bindings
awful.mouse.append_global_mousebindings() binds right-click on the desktop to the main menu and scrolling to tag switching.
12. Global key bindings
awful.keyboard.append_global_keybindings() registers groups for launchers, tags, focus, screens, audio, brightness, screenshots, layouts and the Clay inspector. Number-row bindings address tags by index. Numpad bindings select layouts by index.
See default keybindings for the full list and the keybindings tutorial to add one.
13. Client mouse and key bindings
The request::default_mousebindings and request::default_keybindings handlers register bindings whose callbacks receive the target client. Left-click activates a client. Mod4 with left or right drag moves or resizes it. Keyboard actions include closing, floating, maximising, and moving between screens.
14. Rules
The ruled.client request::rules handler registers defaults for all clients, floating applications, the wlroots application class, and titlebars. Rules apply when a client is managed. See client rules for matching and ordering.
15. Titlebars
request::titlebars builds compositor-drawn titlebars with an icon, title, and floating, maximise, and close buttons. These are server-side decorations. Applications may also draw their own decorations.
Set titlebars_enabled = false in the titlebar rule to disable compositor titlebars.
16. Notifications
ruled.notification supplies a five-second timeout and preferred screen. The request::display handler creates a naughty.layout.box. Change that handler to customise the notification widget, or change the rules for per-application behaviour. See notifications.
17. Sloppy focus
The final mouse::enter handler activates the client under the pointer without raising it. Remove the handler for click-to-focus. See focus configuration.