qservice

qservice is a Qt 6.8 compatible helper library that turns a regular application into a service on Windows, Linux, and macOS.

Goals

• Native service lifecycle support (install, uninstall, run, exec) on Windows, Linux, and macOS
• Clean public API with focused responsibilities
• Minimal dependencies (Qt Core + native platform service managers)
• CMake-first integration, plus optional qmake .pri integration modes
• Clear extension seams for additional platform backends

Requirements

• C++17
• Qt 6.8.x (Qt6::Core)
• Windows, Linux, or macOS for functional service support
• LLVM clang-format available in PATH for local formatting hooks

Git hooks (format before commit/push)

This repository includes versioned hooks in .githooks:

• pre-commit: auto-formats staged C/C++ files and re-stages them.
• pre-push: validates all tracked C/C++ files with clang-format --dry-run --Werror.

Enable hooks once per clone:

.\scripts\setup-git-hooks.ps1

Optional verification:

git config --get core.hooksPath

Versioning

• Project version is defined in the root VERSION.txt file (MAJOR.MINOR.PATCH).
• CMake package version and library ABI version (SOVERSION) are generated from that value.
• qmake library version is also sourced from the same VERSION.txt file.

Build (Windows, Ninja)

cmake --preset ninja-debug -DCMAKE_PREFIX_PATH="C:/Qt/6.8.2/msvc2022_64"
cmake --build --preset ninja-debug
ctest --preset ninja-debug

Build with qmake / Qt Creator

Open qservice.pro directly in Qt Creator and build it with the Qt 6.8.x msvc2022_64 kit. This root project includes:

• qservice-lib.pro (library)
• examples/basic-service/basic-service.pro (example app)
• tests/tests.pro (qmake test suite)

If you only want to build the library target, open qservice-lib.pro directly.

Command-line equivalent:

C:\Qt\6.8.3\msvc2022_64\bin\qmake.exe qservice.pro
nmake

qmake .pri integration modes

1) Link against built library

• Use: qservice.pri
• Scenario: qservice is already built/installed as a library.

QSERVICE_ROOT = C:/dev/qservice-install
include($$QSERVICE_ROOT/qservice.pri)

2) Embed sources directly (no separate library build)

• Use: qservice-embed.pri
• Scenario: compile qservice sources directly into your application target.

QSERVICE_ROOT = C:/dev/qservice
include($$QSERVICE_ROOT/qservice-embed.pri)

Build (Windows, Visual Studio fallback)

cmake --preset vs2022-debug -DCMAKE_PREFIX_PATH="C:/Qt/6.8.2/msvc2022_64"
cmake --build --preset vs2022-debug
ctest --preset vs2022-debug

CLI behavior

ServiceRunner::parse() supports these commands:

• service install [--name <name>] [--display-name <text>] [--description <text>] [--start manual|auto|delayed-auto]
• service uninstall [--name <name>]
• service run [--name <name>]
• service exec [-- ...]
• -exec (alias to service exec)

Usage Example

See examples/basic-service/main.cpp for an end-to-end integration.

Minimal setup:

qservice::ServiceConfig config;
config.name = "MyService";
config.displayName = "My Service";
config.description = "Example service powered by qservice.";

qservice::ServiceHooks hooks;
hooks.execMain = [](const QStringList&) { return 0; };
hooks.onStart = []() {};
hooks.onStop = []() {};

qservice::ServiceRunner runner;
const qservice::ParsedCommand command = runner.parse(argc, argv);
return runner.run(command, config, hooks);

Install as CMake package

cmake --install build/ninja-debug --prefix C:/dev/qservice-install

Then consume via:

find_package(qservice CONFIG REQUIRED)
target_link_libraries(my_app PRIVATE qservice::qservice)

Service installation notes

• install and uninstall require elevated privileges on Windows.

• v1 intentionally does not implement interactive services.

• Linux uses systemd (systemctl) for install/uninstall management.

• macOS uses launchd (launchctl) for install/uninstall management.