pgLab/AGENTS.md

AGENTS.md

pgLab: Qt 6 / C++20 desktop GUI for PostgreSQL.

Layout (link order: core, pgsql -> pglablib -> pglab)

• core/ – generic utilities (SQL lexer, CSV writer, Expected, JSON); no DB access.
• pgsql/ – thin C++ wrapper around libpq (connection, result, params, oids).
• pglablib/ – catalog models, code builders, query generation, connection config.
• pglab/ – the Qt Widgets application (executable).
• tests/ – gtest executables PgsqlTests and pglabtests, plus mygtestutils (Qt PrintTo helpers).
• docs/ – Sphinx user docs; releasenotes/notes – reno notes.

Build and test

CMake + vcpkg is the active build system (VCPKG_ROOT must be set). Qt 6 is not provided by vcpkg; it must be installed on the system.

cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake
cmake --build build
ctest --test-dir build --output-on-failure

• Run one suite: ./build/tests/pglabtests/pglabtests --gtest_filter='SqlLexer*' (same for PgsqlTests).
• -DBUILD_TESTS=OFF skips tests. build/ is git-ignored; the first configure builds dependencies and is slow.
• Run the app headless with QT_QPA_PLATFORM=offscreen ./build/pglab/pglab. It needs a PostgreSQL server for anything useful.

Gotchas

• Tests are registered per executable, so each ctest entry covers a whole suite.
• A new test file must be added to the add_executable list in tests/<suite>/CMakeLists.txt. Sources are listed explicitly, with no globbing. The same goes for new sources in each library's CMakeLists.txt.
• core/test/ is not referenced by any CMake file (its tests are built from tests/pglabtests). Don't expect changes there to be compiled.
• AUTOMOC/AUTOUIC/AUTORCC are on globally, so .ui and .qrc files only need to be listed as sources.
• BOOST_ENABLE_ASSERT_HANDLER is defined; the handler lives in core/my_boost_assert_handler.cpp.
• Commit messages are plain imperative sentences. User-visible changes need a reno note (releasenotes/notes).
• Docs build: pip install -r docs/requirements.txt && sphinx-build -b html docs userdocs.
• Windows (VS 2022) is also a supported platform. Avoid Linux-only code, and don't break WIN32_LEAN_AND_MEAN/NOMINMAX assumptions.