![]() |
Ansel 0.0
A darktable fork - bloat + design vision
|
This file holds the rules. The knowledge lives in doc/.
It used to be both, and grew to 3,177 lines of accumulated findings. A verification pass on 2026-09-29 against 42eca0e8fe checked every falsifiable claim in it and found sixteen that were wrong — including one marked (OPEN) that had been fixed a month earlier, one that forbade a feature the code already implements, and one naming a struct field that does not exist. A file nobody can date is a file nobody can trust, so the findings moved to doc/, where each one carries the commit it was established against.
Named after the path relative to src/ (src/develop/masks/masks_history.h → DT_DEVELOP_MASKS_MASKS_HISTORY_H). #pragma once silently makes a cyclic include graph compile; explicit guards make the same situation greppable. src/darktable.h has an #error tripwire instead of a guard, and no header may include it. Five X-macro headers deliberately have no guard at all and must never get one.
Enforced: python3 tools/pragma_once_to_guards.py --verify, and python3 tools/include_graph.py --summary must keep reporting cycles 0. → doc/architecture-rules.md, doc/include-graph.md
Everything else belongs in the .c. A header that includes more becomes a supply line its consumers never asked for and cannot see. Implementations do not belong in headers either; the one exception is a header whose published interface is inline code.
Enforced: tools/check_unused_includes.sh --changed <ref>. → doc/architecture-rules.md
src/libs/ and src/views/ contain no raw SQL. Database access belongs behind named functions in src/common/ and src/database/. → doc/architecture-rules.md, doc/collection.md
The ONLY thread-safe interface between the pixel pipeline and an IOP module is history, guarded by dev->history_mutex. module->params and module->blend_params belong to the GUI thread. Never call dt_iop_commit_params(module, module->params, ...) from pipeline code — commit from the history snapshot. To push live state to the pipe, use the transient-resync interface dt_dev_transient_params_{set,clear,get,active}. → doc/pipeline-history.md, doc/reorganisation.md
An entry in an existing section is one edit, to data/anselconfig.xml.in. A new section value takes three: the XML, plus data/anselconfig.dtd (the section attribute is an enumerated list; xmllint fails the build otherwise) and tools/generate_prefs.xsl (a section not enumerated there is silently dropped from the UI, with no error).
Measured 2026-09-29 over the 108-commit history of that file: of the 45 commits that added a <dtconfig> entry, 40 touched only the XML and 5 touched the DTD or XSL — and those 5 are exactly the ones introducing a new section. → doc/preferences.md
This tree's history is full of plausible-but-wrong theories that survived source reading and died on the first measurement. Several entries in doc/ exist only to record which theories were killed and how. When you write a finding down, write down the number and the method.
A toast (dt_control_log(), dt_pipeline_message()) fades within seconds, while what such a message says — a module failed, an image was not updated, an export will not come — stays true. Use dt_control_alert(title, message, item) from src/control/user_message.h, next to dt_control_log(): the GUI shows it with dt_gui_alert() from src/gui/alert.h — a small window with one OK button, kept above Ansel's main window (not other applications) until it is clicked, one per title and message — and without a GUI (ansel-cli), where no view would draw a toast, it prints on stderr. Any thread, any layer from common/ up; only gui/ itself calls dt_gui_alert() directly. The message is the kind of failure and carries no value: the same text at every call from one place. What varies — the file, the module, the profile — is item, one line, which the window lists under the message, each once, in a list that scrolls; NULL when there is nothing to list. A value put in the message opens one window per value instead. An item of several values is built with g_strdup_printf() and freed after the call — a module on an image is _("`s` on s"), self->op then dev->image_storage.fullpath. Reuse one of the existing titles ("Module failed", "Export failed", "Not enough memory", …) before inventing one. A failure that repeats as long as its cause lasts — memory running short, where every new request fails again — is dt_control_alert_once(): the same window and list, but once it is closed it does not open again this session for that title and message. A window that needs more than OK — other buttons, a list of its own, a question — is a dt_gui_alert_t object (dt_gui_alert_new() with a kind, then _add_text/_add_widget/_add_button/_show/_destroy), as gui/closing.c uses it. The window itself — frame, modality, Escape, title bar, focus, the macOS specifics — lives entirely in gui/alert.c; a caller never builds or configures it. Toasts remain right for what is fine to miss: progress, confirmation, a passing state. → doc/pipeline-cache.md (the first user: the memory pressure valve)
| Read this | For |
|---|---|
| doc/README.md | the documentation index and how to build |
| doc/reorganisation.md | module map, layering, the direction of travel |
| doc/architecture-rules.md | the five rules above, with the evidence |
| doc/include-graph.md | include guards, cycles, how they are measured |
| doc/preferences.md | the three-edit rule |
| Read this | For |
|---|---|
| doc/pipeline-cache.md | the pixelpipe cache: keys, refcounts, peeks, memory pressure |
| doc/pipeline-history.md | history snapshots, the darkroom worker, the transient slot |
| doc/module-abandon.md | which modules stop mid-run when the pipe abandons it, and how |
| doc/image-mipmap-cache.md | thumbnail invalidation, image cache entry locks |
| doc/raw-roi-cfa.md | RAW-domain ROI offsets, CFA phase, tile-grid dependence |
| doc/resizing-scaling.md | ROI planning and scaling |
| Read this | For |
|---|---|
| doc/colorprofiles.md | profile roles, locks, the derived-profile memo |
| src/colorprofiles/README.md | the module's own map |
| doc/color.md | colour spaces and the working space |
| doc/highlights-reconstruction.md | harmonic highlight reconstruction |
| doc/interpolation.md | which resampling kernel, and why |
| Read this | For |
|---|---|
| doc/masks-geometry.md | brush and polygon outlines and rasters |
| doc/brush-boundary.md | the full boundary account |
| doc/masks-gui.md | gestures, the wheel mapping, the shape manager |
| doc/masks-history.md | refcounted forms, module mask groups, the enclosure |
| doc/masks-enclosure-p2.md | the enclosure plan |
| doc/masks_history_dedup.md | the persistence dedup design |
| doc/overlay-raster.md | how the overlay is drawn |
| Read this | For |
|---|---|
| doc/iop-notes.md | per-module findings (ashift, retouch, toneequal, …) |
| doc/color-picker.md | what a module picker's min/max are, and how their pixels are located |
| doc/drawlayer.md | the drawlayer module in full |
| doc/retouch-result-memo.md | retouch's per-shape memo |
| doc/gtk-patterns.md | layout, focus, repaint and threading patterns |
| doc/shutdown.md | what a quit waits for, and the window that says so |
| doc/darkroom-redraw.md | the centre repaint path, priced |
| doc/thumbtable.md | the thumbnail grid |
| doc/accelerators.md | keyboard shortcuts end to end |
| doc/collection.md | the library module, import and removal |
| doc/removal-undo.md | how removal is undone |
| doc/export.md | export size resolution |
| Read this | For |
|---|---|
| doc/nightly-distribution.md | nightlies, channels, the manifest |
| doc/sentry.md | crash reports and how to fetch one |
| doc/telemetry.md | what is collected |
| doc/static-iop.md | static IOP linking |
| doc/exiv2.md | the bundled Exiv2 |
The full index, including everything not listed here, is doc/README.md.