yacreader/AGENTS.md

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.

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):

cmake --build build --target update_translations

On multi-config generators (Visual Studio / Ninja Multi-Config), include config:

cmake --build build --config Release --target update_translations

Build .qm files:

cmake --build build --target release_translations

Multi-config variant:

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

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.