pgLab/README.md

The program is build with Qt 6.8 using QtCreator and the Visual Studio 2022 C++ compiler.
Only 64-bits builds are actively maintained.

[Documentation](https://eelke.gitlab.io/pgLab/) is generated automatically when a commit is tagged. It also includes releasenotes.
The release notes use collected from git using [reno](https://docs.openstack.org/reno/latest/index.html).

## Dependencies

- boost
- botan
- googletest
- libpq

Boost, Botan, libpq and googletest are provided by vcpkg through the manifest in `vcpkg.json`, so you do not install them manually.

## Required tools

- CMake 3.21 or newer
- A C++20 compiler (GCC or Clang on Linux, Visual Studio 2022 on Windows)
- Qt 6 with the Core, Gui, Widgets, Sql and Concurrent components
- vcpkg, with the `VCPKG_ROOT` environment variable pointing to its checkout
- Ninja or make (optional, for faster builds)
- A PostgreSQL server (only needed to run the application against a database)

## Building

Configure with the vcpkg toolchain file. The first configure downloads and builds the dependencies, which takes a while:

```
cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake
cmake --build build --parallel
```

To skip the test executables, add `-DBUILD_TESTS=OFF` to the configure command.

### Building on Windows

Tested with Visual Studio 2022 (Professional) and Qt 6.8.2 (MSVC 2022, 64-bit). Run these commands from a "x64 Native Tools Command Prompt for VS 2022", with `VCPKG_ROOT` set and Qt installed in `C:\Qt\6.8.2\msvc2022_64`:

```
cmake -S . -B build -G "Visual Studio 17 2022" -A x64 -DCMAKE_TOOLCHAIN_FILE=%VCPKG_ROOT%\scripts\buildsystems\vcpkg.cmake -DCMAKE_PREFIX_PATH=C:/Qt/6.8.2/msvc2022_64
cmake --build build --config Release --parallel
ctest --test-dir build -C Release --output-on-failure
```

The executables are placed in `build\pglab\Release\pglab.exe` and `build\tests\*\Release\`. They need the Qt and vcpkg DLLs next to them. Run `windeployqt` on `pglab.exe` and on each test executable, and copy the vcpkg runtime DLLs from `build\vcpkg_installed\x64-windows\bin` into the same folders. For the app:

```
C:\Qt\6.8.2\msvc2022_64\bin\windeployqt.exe --release build\pglab\Release\pglab.exe
```

If another Qt installation (for example one shipped with another program) is on your `PATH`, its `Qt6Core.dll` may be loaded instead, which causes "entry point not found" errors at startup. Deploying the DLLs next to the executables avoids this.

### Parallel builds with Ninja on Windows

Open an x64 Visual Studio 2022 Developer PowerShell. Ninja requires the compiler and Windows SDK environment from that shell; adding `cl.exe` to `PATH` alone can leave the linker unable to find `kernel32.lib`.

With `VCPKG_ROOT` set, run these PowerShell commands (adjust the Qt path for your installation):

```powershell
cmake -S . -B build/ninja-release -G Ninja -DCMAKE_BUILD_TYPE=Release "-DCMAKE_TOOLCHAIN_FILE=$env:VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake" -DCMAKE_PREFIX_PATH=C:/Qt/6.8.2/msvc2022_64
cmake --build build/ninja-release --parallel 8
$env:PATH = "C:\Qt\6.8.2\msvc2022_64\bin;$PWD\build\ninja-release\vcpkg_installed\x64-windows\bin;$env:PATH"
ctest --test-dir build/ninja-release --output-on-failure
```

`--parallel 8` allows eight build jobs; adjust the number to suit your machine. Ninja also builds in parallel by default. `CMAKE_BUILD_TYPE` selects Release at configure time, and the app is written to `build/ninja-release/pglab/pglab.exe`.

Use a separate build directory when changing generators or adding a toolchain to an existing configuration. The directory above keeps the Ninja configuration separate from an existing Visual Studio build. The Qt prefix and vcpkg toolchain are both needed: Qt is installed separately, while vcpkg supplies the other dependencies.

## Running the tests

From the build directory, run:

```
ctest --output-on-failure
```

## Running the application

The executable is built to `build/pglab/pglab`. On a machine without a display, set `QT_QPA_PLATFORM=offscreen`:

```
./build/pglab/pglab
```