mirror of
https://github.com/YACReader/yacreader
synced 2026-04-12 15:49:53 -04:00
3fede5dabf
All translations have been updated, and translations of the actions in the library have been fixed.
105 lines
4.6 KiB
Markdown
105 lines
4.6 KiB
Markdown
# AGENTS GUIDANCE
|
|
|
|
This file provides guidance to AI agents when working with code in this repository.
|
|
|
|
## Build
|
|
|
|
Out-of-source builds are required. In-source builds will be rejected by CMake.
|
|
|
|
```bash
|
|
cmake -B build -DCMAKE_BUILD_TYPE=Release
|
|
cmake --build build --parallel
|
|
```
|
|
|
|
Build options:
|
|
- `DECOMPRESSION_BACKEND`: `unarr` | `7zip` | `libarchive` (default: 7zip on Windows/macOS, unarr on Linux)
|
|
- `PDF_BACKEND`: `pdfium` | `poppler` | `pdfkit` | `no_pdf` (default: pdfium on Windows, pdfkit on macOS, poppler on Linux)
|
|
- `BUILD_SERVER_STANDALONE=ON`: builds only `YACReaderLibraryServer` (headless), requires only Qt 6.4+
|
|
- `BUILD_TESTS=ON` (default): enables the test suite
|
|
|
|
## Translations
|
|
|
|
Use CMake translation targets (Qt LinguistTools integration), not ad-hoc `lupdate` calls.
|
|
|
|
Update `.ts` files from source code (C++ + QML):
|
|
|
|
```bash
|
|
cmake --build build --target update_translations
|
|
```
|
|
|
|
On multi-config generators (Visual Studio / Ninja Multi-Config), include config:
|
|
|
|
```bash
|
|
cmake --build build --config Release --target update_translations
|
|
```
|
|
|
|
Build `.qm` files:
|
|
|
|
```bash
|
|
cmake --build build --target release_translations
|
|
```
|
|
|
|
Multi-config variant:
|
|
|
|
```bash
|
|
cmake --build build --config Release --target release_translations
|
|
```
|
|
|
|
Important:
|
|
- Do not run `lupdate` only on `qml.qrc` (or only on a subset of files), because that can mark unrelated translations as obsolete.
|
|
- In `YACReaderLibrary`, `qt_add_translations(...)` is configured to scan full target sources and include QML from `qml.qrc`.
|
|
- `update_translations` updates both locale TS files and `*_source.ts` template files for all apps.
|
|
- `*_source.ts` files are translator base templates and must not be treated as shipped locales.
|
|
|
|
## Tests
|
|
|
|
```bash
|
|
ctest --test-dir build --output-on-failure
|
|
```
|
|
|
|
Tests live in `tests/` and are built as Qt Test executables (`compressed_archive_test`, `concurrent_queue_test`).
|
|
|
|
## Code Formatting
|
|
|
|
CI enforces `clang-format`. Run it before committing. There are multiple `.clang-format` files — subdirectories for third-party code have their own to opt out of reformatting. Always run recursively from the repo root via the provided scripts:
|
|
|
|
- Linux: `scripts/clang-format-linux.sh`
|
|
- macOS: `scripts/clang-format-macos.sh`
|
|
- Windows: `scripts\clang-format-windows.cmd` (or `.ps1`)
|
|
|
|
Style is WebKit-based with custom brace wrapping (braces on same line for control flow, new line after functions/classes), no column limit, and `SortIncludes: false`.
|
|
|
|
## Architecture
|
|
|
|
The repo builds three applications that share a common set of static libraries:
|
|
|
|
| App | Description |
|
|
|-----|-------------|
|
|
| `YACReader` | Comic viewer |
|
|
| `YACReaderLibrary` | Comic library manager (GUI) |
|
|
| `YACReaderLibraryServer` | Headless HTTP server |
|
|
|
|
### Static library dependency layers (bottom to top)
|
|
|
|
1. **`yr_global`** — version/global constants, no GUI, used by everything
|
|
2. **`naturalsort`, `concurrent_queue`, `worker`** — utilities
|
|
3. **`common_all`** — shared non-GUI: `ComicDB`, `Folder`, `Bookmarks`, HTTP helpers, cover utils
|
|
4. **`comic_backend`** — comic file abstraction + PDF backend (source varies by `PDF_BACKEND`)
|
|
5. **`cbx_backend`** — compressed archive abstraction (in `compressed_archive/`)
|
|
6. **`db_helper`** — SQLite database layer: schema management, reading lists, query parser
|
|
7. **`library_common`** — library scanning, bundle creation, XML metadata parsing; shared between `YACReaderLibrary` and `YACReaderLibraryServer`
|
|
8. **`common_gui`** — GUI widgets, themes infrastructure, version check (not built in `BUILD_SERVER_STANDALONE`)
|
|
9. **`rhi_flow_reader` / `rhi_flow_library`** — RHI-based 3D coverflow widget, compiled twice with different defines (`YACREADER` vs `YACREADER_LIBRARY`); shaders compiled via `qt_add_shaders()`
|
|
|
|
### Key design notes
|
|
|
|
- **Theme system**: `theme_manager.h/cpp` is NOT part of `common_gui` because it depends on app-specific `Theme` structs. Each app (`YACReader/themes/`, `YACReaderLibrary/themes/`) defines its own `theme.h` and includes `theme_manager` directly.
|
|
- **Compile-time app identity**: `YACREADER` or `YACREADER_LIBRARY` defines distinguish shared source compiled into different apps.
|
|
- **PDF backend**: resolved at configure time into an `INTERFACE` target `pdf_backend_iface` (see `cmake/PdfBackend.cmake`); `comic_backend` and `common_all` link against this interface.
|
|
- **Third-party code**: `third_party/` contains QsLog, KDToolBox, QtWebApp, QrCode — each has its own `.clang-format` to prevent reformatting.
|
|
- **Runtime dependencies**: Qt binaries must be in `PATH`; third-party DLLs/dylibs must be next to the executable. Check an existing YACReader installation for the required files.
|
|
|
|
### PRs
|
|
|
|
Target branch is always `develop`.
|