SomeWM Documentation
A Wayland compositor that brings AwesomeWM's Lua API to Wayland, built on wlroots. These docs cover everything from getting started to the full API reference.
What These Docs Aim to Be
SomeWM's documentation aims to be self-sufficient: a complete reference for SomeWM users, organized so you can find what you need without leaving.
- Comprehensive. Every API surface AwesomeWM documents is, or will be, documented here.
- Organized by task. We use the Diátaxis framework: tutorials (learning), how-to guides (doing), reference (looking up), and concepts (understanding), each kept separate. AwesomeWM's docs are LDoc-generated and do not draw these distinctions.
- Honest about Wayland. Architectural differences from AwesomeWM, stubs, and SomeWM-only extensions are inline on the affected pages and indexed in Deviations.
We are not self-sufficient on every topic yet. If you hit a gap, file a discussion and we will prioritize it. See #532 for the conversation that started this work.
How to Use These Docs
This documentation attempts to follow the Diátaxis framework, organizing content into four distinct types:
| Type | Purpose | When to use |
|---|---|---|
| Tutorials | Learning through doing | You're new and want to learn step-by-step |
| How-To Guides | Solving specific problems | You need to accomplish a particular task |
| Reference | Technical specifications | You need exact details about an API or feature |
| Concepts | Understanding the "why" | You want deeper knowledge of how things work |
Each section serves a different need. Pick the one that matches what you're trying to do.
Getting Started
| Module | Description |
|---|---|
| Installation | Build and install SomeWM |
| First Launch | Run SomeWM for the first time |
| Migrating | Coming from AwesomeWM? Start here |
Tutorials
Step-by-step lessons to learn SomeWM from scratch.
| Module | Description |
|---|---|
| Basics | Core concepts and configuration |
| Keybindings | Set up keyboard shortcuts |
| Widgets | Build custom widgets |
| Wibar | Configure the status bar |
| Theme | Customize colors and appearance |
How-To Guides
Practical recipes for specific tasks.
| Module | Description |
|---|---|
| Input Devices | Configure touchpad, mouse, and keyboard settings |
| CLI Control | Control SomeWM from external scripts |
| Multi-Monitor | Set up multiple displays |
| Autostart | Launch applications on startup |
| Notifications | Configure the notification system |
| Screenshots | Capture screen content |
| Fractional Scaling | HiDPI and fractional display scaling |
Reference
Technical specifications and API details. Organized by Lua library, with links to upstream AwesomeWM docs.
| Module | Description |
|---|---|
| Lua Libraries | Overview of all libraries with upstream links |
| awful | Window management, keybindings, layouts |
| beautiful | Theming and theme variables |
| wibox | Widgets and the wibar |
| naughty | Notifications |
| gears | Utilities (timers, shapes, colors) |
| Key Names | Modifier keys and key name reference |
| somewm-client | IPC CLI tool (SomeWM-only) |
Concepts
Background knowledge and architectural understanding.
| Module | Description |
|---|---|
| Why SomeWM | What this project commits to and what is open |
| Architecture | How SomeWM is structured |
| Object Model | Understanding the Lua object system |
| Wayland vs X11 | Key differences from X11 |
| AwesomeWM Compatibility | What works and what differs |
Versioning
The default docs match SomeWM 1.4, the current stable release, which tracks the AwesomeWM master branch. Use the version switcher in the navigation bar to view the 2.0 (dev) docs — SomeWM 2.0 is a Wayland-native rework that is not yet released.
The AwesomeWM apidoc remains a useful upstream reference for topics that are not yet self-sufficient here.