Development

Prerequisites

• Go 1.22 or later
• wlroots 0.20
• wayland 1.24+
• libxkbcommon
• NixOS (recommended) or equivalent Linux system

Getting Started

NixOS

Enter the development shell:

nix-shell

Building

make build

The binary is output to build/samwm.

Running

./build/samwm

Or with a specific config:

./build/samwm -config /path/to/config.lua

Running Tests

make test

Project Structure

• cmd/samwm/ — Entry point
• internal/compositor/ — Core compositor logic and keybinding handling
• internal/window/ — Window type and management
• internal/layout/ — Tiling layout algorithms
• internal/config/ — Configuration loading
• pkg/wlroots/ — CGo bindings for wlroots-0.20
• pkg/lua/ — Lua scripting VM

Adding Features

Adding a New Layout

1. Create a new file in internal/layout/
2. Implement the Layout interface:

type Layout interface {
    Name() string
    Apply(windows []*window.Window, bounds window.Rect, cfg config.Config)
}

3. Register in layout/manager.go NewManager()

Adding a New Keybinding Action

1. Add a case in internal/compositor/keybind.go executeAction()
2. Implement the action method
3. Add the keybinding to the default config in internal/config/config.go

Adding New wlroots Bindings

1. Add CGo bindings in pkg/wlroots/
2. Use ListenerManager for wayland signal callbacks
3. Add C helper functions for union field access if needed

Debugging

Common Issues

• SIGABRT: renderer != NULL: Ensure wlr_output_init_render is called before wlr_output_layout_add_auto.
• Undefined symbol errors: Ensure all CGo files have the same #cgo pkg-config flags.
• Thread issues: All wlroots operations must happen on the same locked OS thread.

Verbose Logging

./build/samwm -v

Checking wlroots Headers

ls /nix/store/*-wlroots-0.20.0/include/wlroots-0.20/wlr/types/

Build Targets

• make build — Build the binary
• make test — Run tests
• make clean — Remove build artifacts
• make fmt — Format Go code
• make vet — Run go vet