# DWM - Development Rules

## Build System: dwm-flexipatch

This is a **flexipatch** build. Patches are toggled via `#define` flags, NOT by applying `.diff` files.

### Critical File Hierarchy

| File | Role | Committed? |
|------|------|------------|
| `config.def.h` | **Source of truth** for all configuration | YES |
| `patches.def.h` | **Source of truth** for patch enable/disable flags | YES |
| `config.h` | Local working copy (generated from `config.def.h`) | NO (gitignored) |
| `patches.h` | Local working copy (generated from `patches.def.h`) | NO (gitignored) |
| `config.mk` | Compiler/linker flags, library paths | YES |
| `dwm.c` | Core window manager (includes config.h at line 878) | YES |
| `patch/*.c` `patch/*.h` | Patch implementations and headers | YES |
| `patch/include.c` `patch/include.h` | Conditional patch includes (do NOT edit by hand) | YES |

### Rules for Editing Configuration

1. **ALWAYS edit `config.def.h`** for keybindings, layouts, rules, colors, and custom functions.
2. **ALWAYS edit `patches.def.h`** to enable/disable patches (`#define PATCH_NAME 0` or `1`).
3. **ALSO update `config.h` and `patches.h`** to match, so local builds work without regenerating.
4. **NEVER edit only `config.h` or `patches.h`** — those are gitignored and will be lost.
5. When `config.h` does not exist, `make` generates it by copying `config.def.h`. Same for `patches.h`.

### Build & Deploy Process

**Local build (this desktop):**
```bash
cd /home/krisyotam/dev/dwm
sudo make clean install
```

**Deploy to laptop (khr1st):**
```bash
# 1. Commit and push from desktop
cd /home/krisyotam/dev/dwm
git add config.def.h patches.def.h
git commit -m "description"
git push

# 2. SSH to laptop, pull, rebuild
ssh khr1st
cd ~/.local/src/dwm && git pull && sudo make clean install

# 3. Self-restart dwm (preserves all windows — no session kill)
# Trigger via sysact menu or a keybinding mapped to self_restart
```

**NEVER** tell the user to "restart dwm" or "log out and back in" without mentioning self_restart. The SELFRESTART_PATCH is enabled and does an in-place `execv()` that preserves all window positions.

---

## Suckless Coding Style

Reference: https://suckless.org/coding_style/

The following are guidelines. The most important aspect of style is **consistency**.

Recommended reading:
- https://man.openbsd.org/style
- http://doc.cat-v.org/bell_labs/pikestyle
- https://www.kernel.org/doc/Documentation/process/coding-style.rst

### File Layout

Organize files in this order:

1. Comment with LICENSE and file/tool explanation
2. Headers
3. Macros
4. Types
5. Function declarations (include variable names; group logically)
6. Global variables
7. Function definitions matching declaration order
8. `main`

### C Features

- Use **C99 without extensions** (ISO/IEC 9899:1999).
- Use **POSIX.1-2008**: define `_POSIX_C_SOURCE 200809L` or `_XOPEN_SOURCE 700`.
- **Do not mix declarations and code.**
- **Do not use for loop initial declarations** (e.g., `for (int i = 0; ...)`).
- Use `/* */` for comments, **not `//`**.
- Variadic macros are acceptable but be cautious with `__VA_ARGS__`.

### Blocks

- All variable declarations at the **top of the block**.
- `{` on the same line, preceded by a single space (except for function definitions).
- `}` on its own line unless continuing a statement (`} else {`).

Use blocks for single statements only when the inner statement needs blocks:
```c
for (;;) {
	if (foo) {
		bar;
		baz;
	}
}
```

Use blocks when any branch requires them:
```c
if (foo) {
	bar;
} else {
	baz;
	qux;
}
```

### Leading Whitespace

- Use **tabs for indentation** and **spaces for alignment**.
- No tabs except at the beginning of a line.
- Use **spaces** (not tabs) for multiline macros, as the indentation level is 0.

### Functions

- Return type and modifiers on a **separate line**.
- Function name and argument list on the next line.
- Opening `{` on its **own line** (function definitions only).
- Functions not used outside the translation unit must be `static`.

```c
static void
usage(void)
{
	eprintf("usage: %s [file ...]\n", argv0);
}
```

### Variables

- Global variables not used outside the translation unit must be `static`.
- In pointer declarations, `*` is adjacent to the **variable name**, not the type:
  ```c
  char *p;    /* correct */
  char* p;    /* wrong */
  ```

### Keywords

- Use a **space after** `if`, `for`, `while`, `switch` (they are not function calls).
- **No space** after `(` or before `)`.
- Preferably use `()` with `sizeof`.
- **No space** with `sizeof()`:
  ```c
  sizeof(int)   /* correct */
  sizeof (int)  /* wrong */
  ```

### Switch Statements

- **Do not indent cases** another level.
- **Comment cases that fall through.**

```c
switch (value) {
case 0: /* FALLTHROUGH */
case 1:
case 2:
	break;
default:
	break;
}
```

### Headers

- Place **system/libc headers first**, in alphabetical order.
- Add comments if a specific inclusion order is required.
- Place **local headers after an empty line**.
- Avoid cyclic dependencies; include headers only where needed.

### User Defined Types

- **Do not use `type_t` naming** (reserved for POSIX, less readable).
- Typedef opaque structs.
- **Do not typedef builtin types.**
- Use **`CamelCase`** for typedef'd types.

### Line Length

Keep lines to a reasonable length: **max 79 characters**.

### Tests and Boolean Values

- **Do not use C99 `bool`** types. Stick to integer types.
- Use compound assignment and tests unless lines grow too long:
  ```c
  if (!(p = malloc(sizeof(*p))))
  	hcf();
  ```

### Error Handling

- When functions return `-1` for error, **test against `0`**, not `-1`:
  ```c
  if (func() < 0)
  	hcf();
  ```
- Use `goto` to unwind and cleanup when necessary, instead of multiple nested levels.
- `return` or `exit` early on failures instead of deeply nesting.
- Unreachable code should have a `/* NOTREACHED */` comment.
- For fatal errors in one-shot programs, memory freeing may be skipped, but temporary files should be cleaned.

### Enums and #define

Use enums for semantically grouped values. Use `#define` otherwise:
```c
#define MAXSZ  4096
#define MAGIC1 0xdeadbeef

enum {
	DIRECTION_X,
	DIRECTION_Y,
	DIRECTION_Z
};
```

---

## DWM-Specific Conventions

### Naming in dwm

- `CamelCase` for types and structs: `Client`, `Monitor`, `Layout`, `Key`, `Button`
- `lowercase` or `lowercasemultiword` for functions: `focusmon`, `tagmon`, `sendmon`, `killclient`
- `UPPERCASE` for macros and constants: `MODKEY`, `NUMTAGS`, `CLEANMASK`, `SHCMD`
- Enum values: `SchemeNorm`, `SchemeSel`, `NetSupported`

### Comments in Config Files

- `/* C89-style block comments */` in `.c` source files (mandatory per suckless style).
- `// C99 inline comments` are acceptable in `config.def.h` for brief binding annotations only.
- Preprocessor guards: `#endif // PATCH_NAME`

### Conditional Compilation (Patch Guards)

```c
#if SOME_PATCH
/* patch-specific code */
#endif // SOME_PATCH
```
- Always include the patch name in the `#endif` comment.
- Custom (non-patch) code added to `config.def.h` does NOT need guards.

### Adding a Custom Function in config.def.h

Custom functions go **before** the `static const Key keys[]` array. They can reference any forward-declared function from `dwm.c` (`sendmon`, `focusmon`, `arrange`, `focus`, `selmon`, `mons`, etc.) because `config.h` is included after all declarations in `dwm.c` (line 878).

---

## Layout Array Reference

The layout array uses **flextile-deluxe**. Index matters for keybindings.

| Index | Symbol | Layout | Notes |
|-------|--------|--------|-------|
| 0 | `[]=` | Tile | Default |
| 1 | `><>` | Floating | |
| 2 | `[M]` | Monocle | |
| 3 | `\|\|\|` | Columns | |
| 4 | `>M>` | Floating master | |
| 5 | `[D]` | Deck | |
| 6 | `TTT` | Bottom stack | |
| 7 | `===` | Bottom stack horiz | |
| 8 | `\|M\|` | Centered master | |
| 9 | `-M-` | Centered master horiz | |
| 10 | `:::` | Gappless grid | |
| 11 | `[\\]` | Fibonacci dwindle | |
| 12 | `(@)` | Fibonacci spiral | |
| 13 | `[T]` | Tatami mats | |
| 14 | `RRR` | Reading mode (3 vertical panes) | Custom: nmaster=3 |

**When referencing layouts in keybindings, ALWAYS verify the index by counting from 0 in the `layouts[]` array.** Off-by-one errors here cause the wrong layout to activate with no obvious error.

---

## Currently Enabled Patches

Patches set to `1` in `patches.def.h`:

**Bar:** BAR_DWMBLOCKS, BAR_LTSYMBOL, BAR_STATUS, BAR_STATUSCMD, BAR_TAGS, BAR_WINTITLE, BAR_HIDEVACANTTAGS

**Core:** CFACTS, COOL_AUTOSTART, CYCLELAYOUTS, PERTAG, RESTARTSIG, SCRATCHPADS, SEAMLESS_RESTART, SELFRESTART, SHIFTTAG, SHIFTVIEW, STACKER, STICKY, SWALLOW, TOGGLEFULLSCREEN, VANITYGAPS, XRESOURCES

**Layouts:** BSTACK, CENTEREDMASTER, CENTEREDFLOATINGMASTER, COLUMNS, DECK, FIBONACCI_DWINDLE, FIBONACCI_SPIRAL, NROWGRID, TILE, MONOCLE

---

## Current Custom Keybindings

| Binding | Action |
|---------|--------|
| Super+Q | Reading mode (RRR layout) |
| Super+Shift+Q | Kill client (close window) |
| Super+Backspace | sysact (system actions menu) |
| Super+Left/Right/Up/Down | Send window to monitor in that direction |
| Super+Comma/Period | Focus previous/next monitor |
| Super+T | Tile layout |
| Super+F | Floating layout |

---

## Rules for Making Changes

1. **Read before writing.** Always read the relevant section of `config.def.h` before modifying it. Understand the surrounding `#if` guards.
2. **Count layout indices.** Never assume a layout index. Count from 0 in the `layouts[]` array every time.
3. **Check for keybinding conflicts.** Before adding a new binding, grep for the key symbol (e.g., `XK_w`) across `config.def.h` to find all uses and check which patches guard them.
4. **Test compilation.** Clang diagnostics on `config.h` standalone are ALWAYS false positives (missing types like `Arg`, `Client`, `Monitor`). The only valid test is `make` in the repo root.
5. **Keep both files in sync.** Every edit to `config.def.h` must also be applied to `config.h` (and vice versa for patches).
6. **Preserve removed bindings as comments.** When removing a keybinding, comment it out with a `// removed: reason` note rather than deleting the line, so the history is visible.
7. **Do not modify `dwm.c` unless absolutely necessary.** Configuration belongs in `config.def.h`. New functions go in `config.def.h` (before the keys array) or as a new file in `patch/`.
8. **Do not modify `patch/include.c` or `patch/include.h`** unless adding a completely new patch file to the `patch/` directory.
9. **Commit messages:** Imperative mood, concise. Example: `"Rebind reading mode to Super+Q, add directional tagmon"`. No "Co-Authored-By" lines.