Hi (especially the CMake experts), as I uploaded this to Phabricator where no group "Buildsystem" or similiar seems to exist yet, notifying you here manually.
Especially interested in comments on the use of "exported" CMake targets to allow linking between different QCH files (also naming patterns). Cheers Friedrich SUMMARY Enables generation of QCH files during a normal build, for documenting the public API of a library. These macros are especially done with release builds in mind, so distributed packages (like from Linux distributions) can include QCH files matching the version of the library and will be also automatically updated on new versions of the libary. Next to that these macros also support linking between different QCH files, so a subclass from another library for which there also is a QCH file installed will be linked to the entry in that other QCH file. This should be a nice supplement to online services like api.kde.org, like Qt's own QCH files are to doc.qt.io While QCH files from an abstract POV could be seen similar to code libraries, being components with links to lookup symbols/entries in other QCH files, so the rules and code should be done with similar concepts, currently CMake's target system seems bound to executable code creation. So things like "file(EXPORT ...)" could sadly not be reused, as custom targets are not supported with that. Thus a custom macro had to be created for now. Also could I not find a way to use namespaces like KF5::, for more consistent target naming. The patch also adds two variables to KDEInstallDirs.cmake for controlling where the QCH (and respective doxygen tag files) are installed. The QTQCHDIR variant allows to install QCH files for Qt-extending libraries into the same folder where Qt's own QCH files are, so Qt Assistant & other QCH viewer pick up them automatically. Open questions: a) target system for exporting/importing done in a sane way? Better name pattern for the QCH targets than xxx_QCH (see the targets created for Qt, like Qt5Core_QCH)? b) sharing metadata with kapidox Initially I placed these macros into the kapidox module, as this seems the logic place. And would match what kdoctools does for user manuals. Just, that would create a build dependency on kapidox which complicates usage a little. Having these macros in ECM delivers them with no extra effort needed. The data in metainfo.yaml is partially duplicated with the data feed into the macros. How to deduplicate that is still open. Especially with the need to not depend on external data sources like identify.kde.org. Issues: * released current doxygen versions broken and miss to include some files with generated QCH (https://bugzilla.gnome.org/show_bug.cgi?id=773693), fixed only in doxygen development version * Qt Assistant often only built with QTextBrowser, while doxygen uses lots of HTML5 (incl. hardcoded JavaScript) (https://bugzilla.gnome.org/show_bug.cgi? id=773715), needs e.g. distributions to use QtWebKit to work * inter-QCH links do not work in KDevelop currently (see https://bugs.kde.org/ show_bug.cgi?id=372747) Future work: * avoid need to explicitly list all linked QCH targets, have something like public link interfaces (gets complicated with mixes of versioned and unversioned linking possibly) More details/background info at https://frinring.wordpress.com/2016/09/27/adding-api-dox-generation-to-the-build-by-cmake-macros/
