SomeWM Documentation
SomeWM 2.1 is a programmable Wayland compositor built on AwesomeWM's Lua configuration model. Its widget system lets you build the desktop itself: bars, launchers, popups, titlebars and notifications. Make a clock open a calendar, build a control panel for your system, or write your own window layout. Start with the supplied configuration and add what you need.
Start here
| Starting point | Read next |
|---|---|
| I want to try SomeWM | Run it in a window without logging out, or install and launch it. |
| I have a running session and want to build something | Build a clock widget. Create a Lua module, see it on screen, add interaction, then put it in your bar. |
| I have a SomeWM 2.0 configuration | Upgrade to 2.1, including how to port custom widgets. |
| I have an AwesomeWM configuration | Migrate from AwesomeWM and check the widget changes. |
Build your desktop
Start with configuration basics if you have not edited rc.lua before. Then follow the widget path:
- Build a clock widget: a complete example you can see and interact with.
- Build a wibar: place widgets alongside tags, tasks and the system tray.
- Create a custom widget: add your own methods and state, write a Clay description, or display custom Cairo artwork.
Keybindings, Theme and Carousel cover other parts of the desktop. You do not need to read the renderer documentation before building widgets.
Solve a specific task
Update widgets from timers and commands, animate them, or write a client layout. The How-To Guides section in the sidebar lists configuration tasks such as input devices, notifications and multiple monitors.
Reference
| Page | Covers |
|---|---|
| Lua Libraries | every library, with upstream links |
| awful, wibox, beautiful, naughty, gears | the libraries |
| somewm-client | the IPC command line |
| Key Names | keys and modifiers |
| Compatibility reference | platform differences and compatibility limits |
Concepts
- How SomeWM draws: layout and rendering
- Reading the tree: inspect layout results
- The Object Model, Architecture, and Signals: objects and configuration
- Why SomeWM, AwesomeWM Compatibility, and Wayland vs X11: design and compatibility
Versions
2.1 is the newest release. The version switcher has 2.2 in development, 2.0, and 1.4, which mirrors AwesomeWM master and is maintained indefinitely. The AwesomeWM apidoc covers inherited APIs not yet documented here.