After many failed attemps I have managed to build a C++ akonadi client. It has felt like one of the most frustrating programming experiences of my whole life, so I'm sharing the results hoping to spare others from all the suffering.
First thing first, akonadi client libraries are not in libakonadi-dev but in
kdepimlibs5-dev, even if kdepimlibs5-dev does not show in apt-cache search
akonadi.
Then, kdepimlibs is built with Qt4. If your application uses Qt5 (mine was) you need to port it back to Qt4 if you want to talk to Akonadi.
Then, kdepimlibs does not seem to support qmake and does not ship pkg-config
.pc files, and if you want to use kdepimlibs your build system needs to be
cmake. I ported by code from qmake to cmake, and now qtcreator wants me to
run cmake by hand every time I change the CMakeLists.txt file, and it stopped
allowing to add, rename or delete sources.
Finally, most of the code / build system snippets found on the internet seem flawed in a way or another, because the build toolchain of Qt/KDE applications has undergone several redesignins during time, and the network is littered with examples from different eras. The way to obtain template code to start a Qt/KDE project is to use kapptemplate. I have found no getting started tutorial on the internet that said "do not just copy the snippets from here, run kapptemplate instead so you get them up to date".
kapptemplate supports building an "Akonadi Resource" and an "Akonadi Serializer", but it does not support generating template code for an akonadi client. That left me with the feeling that I was dealing with some software that wants to be developed but does not want to be used.
Anyway, now an example of how to interrogate Akonadi exists as is on the internet. I hope that all the tears of blood that I cried this morning have not been cried in vain.