mirror of
https://github.com/storytold/pdfcraft.git
synced 2026-10-25 10:39:01 -06:00
Gert Pellin - GPE
1d31c230c9
The desktop app installed no logger, so every log::warn!/log::error! in the workspace was discarded: a failed autosave, a page that would not render, a render worker that could not start. A launch from a desktop menu has no terminal either, so there was nothing to attach to a bug report. apps/pdfcraft/src/logging.rs (no new dependency besides log): - standard error plus <settings dir>/logs/pdfcraft.log, next to app.ron (Linux $XDG_DATA_HOME/pdfcraft); each launch rotates the previous log to pdfcraft.1.log and .2.log, so the log of a run that crashed survives the next start; the file is capped at 16 MiB - records logged before the settings directory is known are buffered (bounded) and written once the file is attached - default levels: info for pdfcraft*, warn for everything else; RUST_LOG replaces them with env_logger-style directives - never panics: an unusable directory or a failed write leaves standard error as the only sink The logger is installed first in main, so the panic hook's report is recorded too; the start-up messages in main go through it. The file is opened after argument parsing (--version leaves no file) and after the PrintCraft folder migration, which a fresh settings folder would block. Documented in docs/development.md (Logs, environment variables).
34 lines
2.1 KiB
Markdown
34 lines
2.1 KiB
Markdown
# Developing PdfCraft
|
|
|
|
Working instructions for agents and contributors are in `AGENTS.md` and `CLAUDE.md`. This page
|
|
collects what the desktop app reads from its environment and where it writes its diagnostics.
|
|
|
|
## Logs
|
|
|
|
The desktop app writes its `log` records to standard error and to `logs/pdfcraft.log` in its
|
|
settings folder, next to `app.ron`: Linux and FreeBSD `~/.local/share/pdfcraft/logs/` (or
|
|
`$XDG_DATA_HOME/pdfcraft/logs/`), macOS `~/Library/Application Support/PdfCraft/logs/`, Windows
|
|
`%APPDATA%\PdfCraft\data\logs\`. A start from a desktop menu, Finder or the Start menu has no
|
|
terminal, so this file is what to attach to a bug report: a failed autosave, a page that would not
|
|
render, a render worker that could not start and the report of an internal error all land there.
|
|
Each launch moves the previous log to `pdfcraft.1.log` (and that one to `pdfcraft.2.log`), so the
|
|
log of a run that crashed survives the next start. The file stops growing at 16 MiB. `--version`
|
|
writes no file.
|
|
|
|
By default PdfCraft's own crates (`pdfcraft*`) log at `info` and everything else at `warn`.
|
|
`RUST_LOG` replaces that with env_logger-style directives, for example `RUST_LOG=debug`,
|
|
`RUST_LOG=warn,pdfcraft_render=trace` or `RUST_LOG=info,wgpu_core=warn`; a directive ending in `*`
|
|
covers every target starting with it (`pdfcraft*=debug`). The logger is
|
|
`apps/pdfcraft/src/logging.rs`. It never records the control-channel token or document passwords.
|
|
|
|
## Environment variables
|
|
|
|
| Variable | Effect |
|
|
|---|---|
|
|
| `RUST_LOG` | Log levels for standard error and the log file (see [Logs](#logs)) |
|
|
| `RUST_BACKTRACE` | `1` adds a backtrace to the report of an internal error |
|
|
| `XDG_DATA_HOME` | Linux/FreeBSD: base of the settings folder (`pdfcraft/`), the log folder and crash recovery |
|
|
| `WGPU_POWER_PREF` | GPU choice; by default PdfCraft prefers the low-power (integrated) GPU |
|
|
| `WGPU_BACKEND` | Graphics backend; by default Windows uses Direct3D 12, falling back to OpenGL |
|
|
| `CRAFT_FONTS_DIR` | Build time: a [craft-fonts](https://github.com/storytold/craft-fonts) checkout to embed (Japanese fonts) |
|