174 lines
5.2 KiB
Markdown
174 lines
5.2 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
Redshift adjusts screen color temperature according to time of day using gamma ramps. The project consists of:
|
|
- **redshift**: C program that manages color temperature adjustment
|
|
- **redshift-gtk**: Python GUI wrapper providing a system tray status icon
|
|
|
|
## Build System
|
|
|
|
This project uses GNU Autotools (autoconf/automake).
|
|
|
|
### Building from Source
|
|
|
|
```shell
|
|
# Initial setup (only needed after git clone)
|
|
./bootstrap
|
|
|
|
# Configure with prefix for local development
|
|
./configure --prefix=$HOME/redshift/root \
|
|
--with-systemduserunitdir=$HOME/.config/systemd/user
|
|
|
|
# Build
|
|
make
|
|
|
|
# Install to prefix directory
|
|
make install
|
|
|
|
# Run distribution checks
|
|
make distcheck
|
|
```
|
|
|
|
### Platform-Specific Configuration
|
|
|
|
**Linux (full features):**
|
|
```shell
|
|
./configure --enable-drm --enable-vidmode --enable-randr --enable-geoclue2 --enable-gui --enable-apparmor
|
|
```
|
|
|
|
**macOS:**
|
|
```shell
|
|
./configure --enable-corelocation --enable-quartz --enable-gui
|
|
```
|
|
|
|
**Windows (cross-compile with MinGW):**
|
|
```shell
|
|
./configure --disable-drm --disable-randr --disable-vidmode --enable-wingdi \
|
|
--disable-quartz --disable-geoclue2 --disable-corelocation --disable-gui \
|
|
--disable-ubuntu --host=x86_64-w64-mingw32
|
|
```
|
|
|
|
### Running Tests
|
|
|
|
```shell
|
|
# Basic functionality test
|
|
./root/bin/redshift -l 12:-34 -pv
|
|
|
|
# Test with dummy adjustment method
|
|
./root/bin/redshift -l 12:-34 -m dummy -vo
|
|
|
|
# Test with configuration file
|
|
echo -e "[redshift]\ndawn-time=6:30\ndusk-time=18:00-19:30" > test.config
|
|
./root/bin/redshift -c test.config -pv
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Core Components
|
|
|
|
**Main Program (`src/redshift.c`):**
|
|
- Entry point and main event loop
|
|
- Sets display gamma every few seconds/minutes based on solar calculations
|
|
- Handles SIGUSR1 (toggle day/night), SIGINT/SIGTERM (restore gamma and exit)
|
|
- Short transitions (~10s) at startup/signal; long transitions (~50min) otherwise
|
|
|
|
**Adjustment Methods** (gamma ramp manipulation):
|
|
- `gamma-drm.c/h`: DRM method for Linux TTY
|
|
- `gamma-randr.c/h`: RANDR method (preferred for X11, supports multiple outputs)
|
|
- `gamma-vidmode.c/h`: VidMode method (X11, older, single output)
|
|
- `gamma-quartz.c/h`: macOS Quartz
|
|
- `gamma-w32gdi.c/h`: Windows GDI
|
|
- `gamma-dummy.c/h`: No-op for testing
|
|
|
|
**Location Providers** (determine geographic coordinates):
|
|
- `location-manual.c/h`: Manual lat/lon specification
|
|
- `location-geoclue2.c/h`: Automatic location via GeoClue2 (Linux)
|
|
- `location-corelocation.m/h`: macOS CoreLocation (Objective-C)
|
|
|
|
**Supporting Modules:**
|
|
- `solar.c/h`: Solar position calculations for day/night timing
|
|
- `colorramp.c/h`: Color temperature to RGB gamma conversion
|
|
- `config-ini.c/h`: Configuration file parsing
|
|
- `options.c/h`: Command-line option handling
|
|
- `hooks.c/h`: Hook scripts for events
|
|
- `signals.c/h`: Unix signal handling
|
|
- `systemtime.c/h`: System time utilities
|
|
|
|
### GUI Component
|
|
|
|
**redshift-gtk** (Python):
|
|
- Located in `src/redshift-gtk/`
|
|
- `controller.py`: Manages redshift subprocess
|
|
- `statusicon.py`: System tray icon
|
|
- `utils.py`: Utility functions
|
|
- Sends SIGUSR1 to redshift when user clicks icon
|
|
|
|
### Conditional Compilation
|
|
|
|
Features are enabled/disabled via autoconf (`configure.ac`). The `src/Makefile.am` conditionally includes source files based on:
|
|
- `ENABLE_DRM`, `ENABLE_RANDR`, `ENABLE_VIDMODE`, `ENABLE_QUARTZ`, `ENABLE_WINGDI`
|
|
- `ENABLE_GEOCLUE2`, `ENABLE_CORELOCATION`
|
|
- `ENABLE_GUI`, `ENABLE_UBUNTU`, `ENABLE_SYSTEMD`, `ENABLE_APPARMOR`
|
|
|
|
## C Coding Style (from CONTRIBUTING.md)
|
|
|
|
- Follow Linux kernel coding style
|
|
- Max 80 characters per line in new code
|
|
- All structures are typedef'd
|
|
- No Yoda conditions
|
|
- No multiline if-statements without braces (use single line or add braces)
|
|
- C-style comments only (`/* */`)
|
|
|
|
## Dependencies
|
|
|
|
**Build tools:**
|
|
- autotools, gettext, intltool, libtool
|
|
|
|
**Optional runtime (Linux):**
|
|
- libdrm (DRM support)
|
|
- libxcb, libxcb-randr (RandR support)
|
|
- libX11, libXxf86vm (VidMode support)
|
|
- glib-2.0, gio-2.0 >= 2.26 (GeoClue2 support)
|
|
|
|
**Optional GUI:**
|
|
- python3 >= 3.2, pygobject, pyxdg
|
|
- appindicator (Ubuntu-style status icon)
|
|
|
|
See `.travis.yml` for Ubuntu package list.
|
|
|
|
## Configuration
|
|
|
|
Configuration file location:
|
|
- **Linux/macOS**: `~/.config/redshift.conf`
|
|
- **Windows**: `%USERPROFILE%\AppData\Local\redshift.conf`
|
|
|
|
Sample: `redshift.conf.sample`
|
|
|
|
## Location Provider Syntax
|
|
|
|
Command-line location syntax: `-l PROVIDER:OPTIONS`
|
|
|
|
Special case: `-l LAT:LON` (parsed as manual provider when LAT is numeric)
|
|
|
|
Example: `-l manual:lat=55:lon=12` is equivalent to `-l 55:12`
|
|
|
|
Longitudes in western hemisphere must be negative (e.g., New York: `41,-74`)
|
|
|
|
## Translation Updates
|
|
|
|
```shell
|
|
make update-po
|
|
```
|
|
|
|
Translations are managed via [Launchpad Translations for Redshift](https://translations.launchpad.net/redshift).
|
|
|
|
## Notes
|
|
|
|
- Verbose logging is controlled in `redshift.c`; all verbose messages should be written there
|
|
- Location providers are only queried at startup, not during runtime
|
|
- Gamma ramps are the mechanism for color adjustment; other applications (games, video players) may temporarily reset them
|
|
- Wayland and Mir are not supported; users should use desktop environment's built-in night light features (GNOME Night Light, KDE Night Color)
|