33 lines
2.8 KiB
Markdown
33 lines
2.8 KiB
Markdown
# 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`).
|
||
- Integration tests against real PostgreSQL 14–17 (`IntegrationTests`, label `integration`): configure with `-DPGLAB_INTEGRATION_TESTS=ON` (needs Docker), then `ctest --test-dir build -L integration -j4`. This starts `tests/integration/docker-compose.yml` (ports 54314–54317), runs the binary once per version and tears it down. Manual run against any server: `TEST_DATABASE_URL=postgresql://postgres:test@localhost:54316/postgres ./build/tests/integration/IntegrationTests --gtest_filter='Smoke*'`. Without the variable the tests skip. Developer-facing only, no reno note. See the `pg-integration-tests` skill.
|
||
- `-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.
|