|
| 1 | +# Repository Guidelines |
| 2 | + |
| 3 | +Xreader is a GTK 3 document viewer (PDF, PostScript, and other formats) developed by Linux Mint, written in C/C++ and built with Meson. This guide covers how to build, test, and contribute to the codebase. |
| 4 | + |
| 5 | +## Project Structure & Module Organization |
| 6 | + |
| 7 | +- `shell/` — the main application: window, menus, sidebars, and UI logic (`ev-*.c`) |
| 8 | +- `libdocument/`, `libview/`, `libmisc/` — the `libxreaderdocument` and `libxreaderview` core libraries |
| 9 | +- `backend/` — format-specific renderers, one directory per type (`pdf`, `ps`, `dvi`, `tiff`, `xps`, `comics`, `djvu`, `pixbuf`) |
| 10 | +- `previewer/`, `thumbnailer/` — optional helper programs |
| 11 | +- `data/` — icons, GSettings schema, `.desktop`/`.appdata` files |
| 12 | +- `po/` — translations; `help/` — Yelp help; `install-scripts/` — Meson install helpers |
| 13 | +- `test/` — UI test scripts and PDF fixtures |
| 14 | +- `debian/` — Debian packaging; `xreader-document.h` and `xreader-view.h` are the public headers |
| 15 | + |
| 16 | +## Build, Test, and Development Commands |
| 17 | + |
| 18 | +Configure with Meson, then compile with Ninja: |
| 19 | + |
| 20 | +```bash |
| 21 | +meson builddir --prefix=/usr/local --buildtype=plain \ |
| 22 | + -D djvu=true -D dvi=true -D pixbuf=true -D comics=true -D introspection=true |
| 23 | +ninja -C builddir # build |
| 24 | +sudo ninja -C builddir install # install |
| 25 | +/usr/local/bin/xreader # run |
| 26 | +``` |
| 27 | + |
| 28 | +Toggle backends with the `-D` options defined in `meson_options.txt`. Enable runtime debugging with `G_MESSAGES_DEBUG=all xreader`. |
| 29 | + |
| 30 | +Run the UI test suite: |
| 31 | + |
| 32 | +```bash |
| 33 | +ninja test -C builddir |
| 34 | +``` |
| 35 | + |
| 36 | +## Coding Style & Naming Conventions |
| 37 | + |
| 38 | +- C/C++ uses **tabs** for indentation and follows GNOME / Linux Mint conventions. See the [Linux Mint Developer Guide](https://linuxmint-developer-guide.readthedocs.io/en/latest/guidelines.html). |
| 39 | +- Keep the `ev-` filename and symbol prefix (e.g. `ev-window.c`, `ev-application.c`). |
| 40 | +- Preserve the GPLv2 license header in every source file. |
| 41 | +- Python test scripts use 4-space indentation. |
| 42 | +- No formatter or linter is enforced; match the surrounding file's style. |
| 43 | + |
| 44 | +## Testing Guidelines |
| 45 | + |
| 46 | +Tests are Python UI-automation scripts (dogtail / `pyatspi`) in `test/`, one per menu or feature (`testZoom.py`, `testFileMenu.py`, `testGoMenu.py`). Shared helpers live in `testCommon.py` (`run_app`, `bail`), which drives the installed binary using the PDF fixtures alongside the scripts. Register new cases in the `test_cases` list in `test/meson.build`. Tests run sequentially with a 120s timeout. |
| 47 | + |
| 48 | +## Commit & Pull Request Guidelines |
| 49 | + |
| 50 | +- Commit subjects are concise, often scoped with a component prefix: `ev-window.c: ...`, `l10n: Update POT`, `epub: ...`. |
| 51 | +- Release by bumping the version in `meson.build` and packaging via `debian/`. |
| 52 | +- PRs should describe the change, link the related issue, and pass the CI build (`.github/workflows/build.yml`). Comment `/generate-test-packages` on a PR to receive a test `.deb`. |
| 53 | +- File bugs using `.github/ISSUE_TEMPLATE/bug_report.yaml`; feature requests belong in [Linux Mint discussions](https://github.com/orgs/linuxmint/discussions). |
0 commit comments