How sharpbracket/redshift works
1. This repository is a cross-platform color-temperature adjustment tool. The core product is the redshift command-line program, with an optional redshift-gtk graphical wrapper that provides a tray/status icon.
2. The architecture is centered in src/ and is split into a small orchestration layer plus platform-specific adapters. The main executable (src/redshift.c) ties together option parsing, configuration, location lookup, solar/time calculations, and gamma-ramp updates.
3. Configuration and startup flow go through options.c and config-ini.c. These read CLI flags and redshift.conf, producing the runtime parameters that control location, transition behavior, brightness, and backend selection.
4. Location is abstracted behind multiple providers. The repo includes manual coordinates, GeoClue2 on Linux, and CoreLocation on macOS. This is the input side of the scheduling pipeline: once coordinates are known, the app computes local sunrise/sunset behavior.
5. Time-of-day logic lives in solar.c and systemtime.c. These modules convert location and current time into the target color temperature for the current moment, so the effect can transition smoothly between daytime and nighttime values.
6. The display-adjustment boundary is implemented by backend-specific gamma modules: gamma-randr.c, gamma-vidmode.c, gamma-drm.c, gamma-quartz.c, gamma-w32gdi.c, and gamma-dummy.c. This is the most important abstraction in the project: the rest of the program computes “what color temperature should we apply?”, and the backend layer answers “how do we set it on this platform?”
7. colorramp.c is the shared transformation layer used by the backends. It builds and applies the actual gamma ramps/curves that produce the redness effect described in the README, including the “brightness” effect that is implemented as gamma manipulation rather than backlight control.
8. Runtime control and process coordination are handled by utility modules such as signals.c, hooks.c, and pipeutils.c. These support clean shutdown, signal handling, and any subprocess/pipe interaction needed by the wrapper or platform integrations.
9. src/redshift-gtk/ is a separate Python frontend. It contains a controller and status-icon implementation that manage the user-facing tray app, likely by launching and supervising the main Redshift process rather than reimplementing the display logic.
10. The project is explicitly packaged for multiple operating systems and desktop environments. The tree includes systemd user services, desktop entries, AppArmor policy, macOS launchd support, Windows resource files, and a sample config/man page, indicating that deployment integration is a first-class part of the architecture.
11. Build and release infrastructure is autotools-based (configure.ac, Makefile.am, bootstrap) with translation support under po/. That means the source tree is organized for portable native builds, and UI strings are localized across many languages.
12. The key external dependencies and service boundaries are platform services, not cloud APIs: X11/Wayland-adjacent gamma facilities, GeoClue2 on Linux, CoreLocation on macOS, GTK/Python for the tray UI, and systemd/launchd/Windows service-style packaging around the core binary.
13. For an architecture diagram, the main boxes are: user configuration and UI on the left; orchestration/scheduling in the center; location and time inputs below; and platform-specific gamma backends on the right, with packaging/integration artifacts surrounding the runtime on each supported OS.
Main entry points: redshift.c redshift · controller.py redshift-gtk · config-ini.c Config INI · configure.ac Autotools
Components 23
UI & Packaging
User-facing wrapper and deployment artifacts around the core binary.
- redshift-gtk · GTK tray/status-icon frontend that supervises the core program.
src/redshift-gtk/controller.py - Status Icon · Tray/status icon presentation and user interaction layer.
src/redshift-gtk/statusicon.py - Packaging · Desktop entries, services, launchd, AppArmor, Windows resources, and sample config.
data/systemd/redshift.service.in
Core Engine
Runtime orchestration, scheduling, and color adjustment pipeline.
- redshift · Main executable that orchestrates parsing, location, timing, and output updates.
src/redshift.c - Options · Reads command-line flags and startup options.
src/options.c - Config INI · Parses redshift.conf and produces runtime settings.
src/config-ini.c - Solar · Computes sunrise/sunset-based transition timing from coordinates.
src/solar.c - System Time · Provides current time and local time-of-day inputs.
src/systemtime.c - Color Ramp · Builds and applies gamma ramps and brightness-related curves.
src/colorramp.c - Signals · Handles shutdown and signal coordination.
src/signals.c - Hooks · Runs external hooks or coordinated actions around runtime events.
src/hooks.c - Pipe Utils · Utility support for subprocess and pipe interactions.
src/pipeutils.c
Platform Backends
OS-specific location and gamma adapters.
- Manual Location · Uses user-supplied coordinates.
src/location-manual.c - GeoClue2 · Linux location backend using GeoClue2.
src/location-geoclue2.c - CoreLocation · macOS location backend using CoreLocation.
src/location-corelocation.m - RANDR · X11 RANDR gamma backend.
src/gamma-randr.c - VidMode · X11 VidMode gamma backend.
src/gamma-vidmode.c - DRM · Direct rendering gamma backend.
src/gamma-drm.c - Quartz · macOS Quartz gamma backend.
src/gamma-quartz.c - W32 GDI · Windows GDI gamma backend.
src/gamma-w32gdi.c - Dummy · No-op backend for unsupported or testing cases.
src/gamma-dummy.c
Build & Locales
Portable build system and translation assets.
- Autotools · configure.ac, Makefile.am, and bootstrap-based native build tooling.
configure.ac - Translations · Message catalogs and translation metadata.
po/POTFILES.in
Connections 27
- redshift → Options: parse · Loads CLI options at startup.
- redshift → Config INI: load · Merges configuration file settings.
- redshift → Manual Location: location · Uses manual coordinates when selected.
- redshift → GeoClue2: location · Queries Linux location service when available.
- redshift → CoreLocation: location · Queries macOS location service when available.
- redshift → Solar: schedule · Computes transition timing from location.
- redshift → System Time: clock · Reads current time for transition state.
- redshift → Color Ramp: apply · Generates and applies the target gamma ramp.
- redshift → RANDR: backend · Uses X11 RANDR output path.
- redshift → VidMode: backend · Uses X11 VidMode output path.
- redshift → DRM: backend · Uses DRM output path.
- redshift → Quartz: backend · Uses macOS gamma path.
- redshift → W32 GDI: backend · Uses Windows gamma path.
- redshift → Dummy: fallback · Uses no-op backend when needed.
- redshift → Signals: lifecycle · Coordinates clean shutdown and signal handling.
- redshift → Hooks: events · Triggers runtime hooks around state changes.
- redshift-gtk → Status Icon: ui · Provides the tray/status icon experience.
- redshift-gtk → Pipe Utils: supervise · Relies on process and pipe helpers to manage the core app.
- redshift-gtk → redshift: launch · Starts and supervises the core Redshift process.
- Packaging → redshift: deploy · Packages the main CLI binary for multiple platforms.
- Packaging → redshift-gtk: deploy · Packages the GTK wrapper and desktop integration.
- Autotools → redshift: build · Builds the core executable.
- Autotools → redshift-gtk: build · Builds the Python/GTK frontend assets.
- Autotools → Translations: localize · Integrates message catalogs into builds.
- Options → Config INI: merge · CLI overrides config-file defaults.
- Config INI → Manual Location: select · Chooses the configured location source.
- Config INI → RANDR: select · Chooses the configured gamma backend.