# Building from Source

Compile DWN for development or custom builds

## Requirements

- Linux with X11 (Xorg)
- GCC compiler (or Clang)
- GNU Make
- pkg-config

## Dependencies

### Required Libraries

Library | Purpose
--- | ---
libX11 | Core X11 protocol
libXext | X11 extensions
libXinerama | Multi-monitor support
libXrandr | Display configuration
libXft | Font rendering
libXtst | Input simulation (API)
fontconfig | Font discovery
libdbus-1 | Notifications
libcurl | HTTP for AI features
libpng | Screenshot encoding
libtesseract | OCR text extraction
libleptonica | Image processing for OCR

### Ubuntu / Debian

    sudo apt update && sudo apt install -y \
        build-essential \
        pkg-config \
        libx11-dev \
        libxext-dev \
        libxinerama-dev \
        libxrandr-dev \
        libxft-dev \
        libxtst-dev \
        libfontconfig1-dev \
        libdbus-1-dev \
        libcurl4-openssl-dev \
        libpng-dev \
        libtesseract-dev \
        libleptonica-dev \
        tesseract-ocr \
        tesseract-ocr-eng

### Fedora / RHEL

    sudo dnf install -y \
        gcc make \
        pkg-config \
        libX11-devel \
        libXext-devel \
        libXinerama-devel \
        libXrandr-devel \
        libXtst-devel \
        dbus-devel \
        libcurl-devel \
        libpng-devel \
        tesseract-devel \
        leptonica-devel \
        tesseract-langpack-eng

### Arch Linux

    sudo pacman -S --needed \
        base-devel \
        pkg-config \
        libx11 \
        libxext \
        libxinerama \
        libxrandr \
        libxtst \
        dbus \
        curl \
        libpng \
        tesseract \
        tesseract-data-eng \
        leptonica

### Automatic Installation

The Makefile can auto-detect your package manager:

    make deps

## Building

### Clone Repository

    git clone https://github.com/retoor/dwn.git
    cd dwn

### Build Release

    make

Output: `bin/dwn`

### Build Debug

    make debug

Includes debug symbols (`-g`) and `-DDEBUG` define.

### Build with Sanitizers

    make sanitize

Enables AddressSanitizer and UndefinedBehaviorSanitizer for debugging memory issues.

### Install System-wide

    sudo make install

Installs to:

- `/usr/local/bin/dwn` - Binary
- `/usr/local/share/xsessions/dwn.desktop` - Session file
- `/etc/dwn/config.example` - Example config

### Custom Prefix

    make PREFIX=/opt/dwn install

## Make Targets

Target | Description
--- | ---
`make` | Build release version (optimized)
`make debug` | Build with debug symbols
`make sanitize` | Build with sanitizers
`make clean` | Remove build artifacts
`make install` | Install to PREFIX
`make uninstall` | Remove installation
`make run` | Test in Xephyr
`make deps` | Install dependencies
`make format` | Run clang-format
`make check` | Run cppcheck static analysis

## Development

### Testing in Xephyr

Test without affecting your current session:

    # Automatic (recommended)
    make run

    # Manual
    Xephyr :1 -screen 1920x1080 &
    DISPLAY=:1 ./bin/dwn

### Code Formatting

    make format

Uses clang-format with project style.

### Static Analysis

    make check

Runs cppcheck for common issues.

### Debug Logging

Debug builds write to `~/.local/share/dwn/dwn.log`:

    tail -f ~/.local/share/dwn/dwn.log

### Directory Structure

    dwn/
    ├── include/        # Header files
    │   ├── dwn.h       # Main state struct
    │   ├── client.h    # Window management
    │   ├── workspace.h # Virtual desktops
    │   ├── layout.h    # Layout algorithms
    │   ├── panel.h     # Panels
    │   ├── api.h       # WebSocket API
    │   ├── screenshot.h
    │   ├── ocr.h
    │   └── ...
    ├── src/            # Implementation
    │   ├── main.c      # Entry point, event loop
    │   ├── client.c
    │   ├── workspace.c
    │   ├── layout.c
    │   ├── panel.c
    │   ├── api.c
    │   ├── screenshot.c
    │   ├── ocr.c
    │   └── ...
    ├── build/          # Object files
    ├── bin/            # Output binary
    ├── examples/       # Client examples
    ├── manual/         # Documentation
    ├── Makefile
    └── CLAUDE.md       # Development guide

### Adding a New Module

1. Create `include/newmodule.h` with public API
2. Create `src/newmodule.c` with implementation
3. Add `newmodule_init()` call to `main.c:dwn_init()`
4. Add `newmodule_cleanup()` call to `main.c:dwn_cleanup()`
5. Makefile automatically picks up new .c files

## Troubleshooting

### Missing pkg-config

    # Check if library is found
    pkg-config --cflags --libs x11

    # If not found, install dev package
    sudo apt install libx11-dev  # Debian/Ubuntu

### Tesseract not found

    # Check installation
    pkg-config --cflags --libs tesseract

    # Install if missing
    sudo apt install libtesseract-dev tesseract-ocr tesseract-ocr-eng

### Linker errors

Ensure all -dev packages are installed. The Makefile uses pkg-config to find libraries.

### Runtime errors

1. Check log file: `~/.local/share/dwn/dwn.log`
2. Build with debug: `make clean && make debug`
3. Build with sanitizers: `make clean && make sanitize`
4. Run in GDB: `DISPLAY=:1 gdb ./bin/dwn`

### X11 errors

Run with synchronous X11 for detailed errors:

    DISPLAY=:1 ./bin/dwn --sync

### Xephyr not starting

    # Check if display :1 is in use
    ls /tmp/.X11-unix/

    # Use different display
    Xephyr :2 -screen 1920x1080 &
    DISPLAY=:2 ./bin/dwn