evileko/evil
1
0
Fork 0
Code Wiki Activity
Page: Home
Pages
Architecture and Philosophy Configuration Guide Contributor Validation Matrix Drawing and Visuals Example Configs Overview Example Shared Helpers Example TTY Baseline Example Tiling Feature Status and Limitations Feature and Support Matrix Getting Started Home Hook Payload Summary Hooks Guide IPC Protocol Lua API Cheat Sheet Lua API Guide Lua Basics for evil Queries Commands and Actions Recipes Testing and Debugging Writing Your First Config
11 Home
Agent edited this page 2026-05-26 05:47:03 -04:00
Table of Contents

evil wiki

Welcome to the long-form documentation for evil, the evil compositor.

This wiki is the place for the slow, detailed explanations that would be too large or too noisy for the repository README.

If you are here because you want to learn how evil works or how to write your own config, this is the right place.

Quick reference

What evil is

evil is an experimental Wayland compositor built around a shared infinite canvas.

That means:

  • windows live in world coordinates
  • outputs act like cameras looking into that world
  • the user experience is heavily shaped by Lua policy

The most important idea in the whole project is:

  • Rust provides facts
  • Lua provides policy

Rust owns runtime truth, rendering, validation, and protocol integration. Lua decides what the desktop should actually do with those facts.

That is why the wiki spends so much time on configs, hooks, and example policies.

Start here

If you are new, read these pages in order:

  1. Getting started
  2. Writing your first config
  3. Lua basics for evil users
  4. Lua API guide
  5. Hooks guide
  6. Example configs overview

That path will take you from:

  • “what is this project?”
  • to
  • “I can read the example configs and start changing them myself.”

If your main goal is writing a config

Read this page first:

That page explains, in detail:

  • how a config is usually structured
  • what each section does
  • why the code is written that way
  • how to use helper functions
  • how to add binds and hooks
  • how to grow a config slowly without getting lost

Then use these:

If you want to learn by editing examples

Start here:

Then read whichever example matches what you want:

If you want to understand the project itself

Read these pages:

These explain how evil is structured and what is already real today.

If you are contributing or debugging

Read these pages:

These are useful if you are:

  • changing code
  • testing a new config idea
  • trying to understand what is fully supported vs still narrow

Current project reality

Today, evil is best understood as three things at once:

  1. a pure core library (the evil core library) for geometry, focus, placement, rules, outputs, and bindings
  2. a deterministic headless runtime for policy development and testing
  3. a real live compositor with a practical nested winit path and an early standalone udev / tty path

It is already useful for:

  • experimenting with scripted desktop behavior
  • iterating on focus, movement, resize, placement, and drawing policy in Lua
  • building custom workflows against both a headless runtime and a real live compositor
  • learning from several real example configs with detailed walkthroughs in this wiki

Feature overview

Area Current picture
Core canvas / window / output logic strong foundation
Headless runtime practical and heavily testable
Nested winit compositor the main live path and a good place to actually use and iterate on configs
Lua config + hook surface real, useful, and expanding
Example configs several serious starting points, including tiling and tty-focused profiles
TTY / standalone backend real and usable, but still the least settled path
Desktop / protocol coverage several important slices are real already, with broader coverage still growing
Documentation wiki-first, with detailed guides for config writing, API use, examples, and debugging

The biggest areas still evolving are:

  • standalone tty confidence and recovery behavior
  • broader desktop / protocol coverage beyond the current proven slices
  • long-term Lua API stabilization and cleanup

Related repo docs

The wiki is the long-form home, but the repository still has useful shorter docs:

  • README.md — short project front page
  • CONTRIBUTING.md — contributor workflow and expectations
  • tests/testing.md — practical testing guide
  • docs/llms.md — dense status / maintainer context
  • docs/dev/plan.md — implementation plan

evil wiki