<table><tr><td style="">kossebau retitled this revision from "New: ECMGenerateApiDox, for generating qch & tag files" to "New: ECMAddQCH, for generating qch & doxygen tag files".<br />kossebau updated the summary for this revision. <a href="https://phabricator.kde.org/transactions/detail/PHID-XACT-DREV-gh2xbg5447klloq/" rel="noreferrer">(Show Details)</a><br />kossebau updated the test plan for this revision. <a href="https://phabricator.kde.org/transactions/detail/PHID-XACT-DREV-m7pcpwznzv5ettf/" rel="noreferrer">(Show Details)</a><br />kossebau added a reviewer: Frameworks.<br />kossebau removed a subscriber: Frameworks.
</td><a style="text-decoration: none; padding: 4px 8px; margin: 0 8px 8px; float: right; color: #464C5C; font-weight: bold; border-radius: 3px; background-color: #F7F7F9; background-image: linear-gradient(to bottom,#fff,#f1f0f1); display: inline-block; border: 1px solid rgba(71,87,120,.2);" href="https://phabricator.kde.org/D2854" rel="noreferrer">View Revision</a></tr></table><br /><div><strong>EDIT DETAILS</strong><div><div style="white-space: pre-wrap; color: #74777D;"><span style="padding: 0 2px; color: #802b2b; background: rgba(251, 175, 175, .7);">DRAFT: feedback wanted<br />
<br />
</span>To enable creation of qch files during a normal build, <div style="padding: 8px 0;">...</div>like Qt's qch files are to doc.qt.io<br />
<br />
<span style="padding: 0 2px; color: #802b2b; background: rgba(251, 175, 175, .7);">Open questions:<br />
a) recommended install path for qch and tag files?<br />
What would KDevelop & Co</span><span style="padding: 0 2px; color: #3e6d35; background: rgba(151, 234, 151, .6);">While QCH files from an abstract POV could be seen similar to code libraries, being components with<br />
links to lookup symbols/entries in other QCH files, so the rules and code should be done with similar concepts,<br />
currently CMake's target system seems bound to executable code creation.<br />
So things like "file(EXPORT ...)" could sadly not be reused, as custom targets are not supported with that</span>. <span style="padding: 0 2px; color: #802b2b; background: rgba(251, 175, 175, .7);">like for easy automatic discovery of qch files?<br />
What would be</span><span style="padding: 0 2px; color: #3e6d35; background: rgba(151, 234, 151, .6);">Thus a custom macro had to be created for now.</span> <span style="padding: 0 2px; color: #802b2b; background: rgba(251, 175, 175, .7);">a nice var name for such dirs</span><span style="padding: 0 2px; color: #3e6d35; background: rgba(151, 234, 151, .6);">Also could I not find a way</span> to <span style="padding: 0 2px; color: #802b2b; background: rgba(251, 175, 175, .7);">be used with KDEInstallDirs?<br />
<br />
b) best way to specify sources to</span><span style="padding: 0 2px; color: #3e6d35; background: rgba(151, 234, 151, .6);">use namespaces like KF5::,</span> <span style="padding: 0 2px; color: #802b2b; background: rgba(251, 175, 175, .7);">use for created API docs?<br />
SOURCE_DIRS in this draft is the only option to specify the input to<br />
doxygen, following the inspiration of kde-dev-scripts/kdedoxyqt.sh.<br />
Being part of the buildsystem and having access to more</span><span style="padding: 0 2px; color: #3e6d35; background: rgba(151, 234, 151, .6);">for more consistent target naming.<br />
<br />
Open questions:<br />
a) recommended install path for qch and tag files?<br />
What would Qt Assistant, Qt Creator,</span> <span style="padding: 0 2px; color: #802b2b; background: rgba(251, 175, 175, .7);">data like sources<br />
for</span><span style="padding: 0 2px; color: #3e6d35; background: rgba(151, 234, 151, .6);">KDevelop & Co.</span> <span style="padding: 0 2px; color: #802b2b; background: rgba(251, 175, 175, .7);">a library target or even special target metadata,</span><span style="padding: 0 2px; color: #3e6d35; background: rgba(151, 234, 151, .6);">like for easy automatic discovery of qch files?<br />
What would be a nice var name for such dirs to be</span> <span style="padding: 0 2px; color: #802b2b; background: rgba(251, 175, 175, .7);">supporting other variants<br />
might be nice to have.</span><span style="padding: 0 2px; color: #3e6d35; background: rgba(151, 234, 151, .6);">used with KDEInstallDirs?<br />
<br />
b) target system for exporting/importing done in a sane way?</span> <span style="padding: 0 2px; color: #802b2b; background: rgba(251, 175, 175, .7);">Looking</span><span style="padding: 0 2px; color: #3e6d35; background: rgba(151, 234, 151, .6);">Better name pattern</span> for <span style="padding: 0 2px; color: #802b2b; background: rgba(251, 175, 175, .7);">proposals from experienced target<br />
metadata</span><span style="padding: 0 2px; color: #3e6d35; background: rgba(151, 234, 151, .6);">the QCH targets than xxx_QCH (see the targets created for Qt,</span> <span style="padding: 0 2px; color: #802b2b; background: rgba(251, 175, 175, .7);">users here.</span><span style="padding: 0 2px; color: #3e6d35; background: rgba(151, 234, 151, .6);">like Qt5Core_QCH)?</span><br />
<br />
c) sharing metadata with kapidox<div style="padding: 8px 0;">...</div>to not depend on external data sources like identify.kde.org.<br />
<br />
<span style="padding: 0 2px; color: #802b2b; background: rgba(251, 175, 175, .7);">d) naming pattern for cmake config variables for qch & tag files sane?<br />
<br />
Issues:<br />
* html style in assistant sometimes co</span><span style="padding: 0 2px; color: #3e6d35; background: rgba(151, 234, 151, .6);">Issues:<br />
* 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<br />
* 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<br />
* inter-QCH links do not work in KDevelop currently (see https://bugs.kde.org/show_bug.cgi?id=372747)<br />
<br />
Future work:<br />
* avoid need to explicitly list all linked QCH targets, have something like public link interfaces (gets complicated with mixes of versioned and un</span>vers<span style="padding: 0 2px; color: #802b2b; background: rgba(251, 175, 175, .7);"> class names</span><span style="padding: 0 2px; color: #3e6d35; background: rgba(151, 234, 151, .6);">ioned linking possibly)</span><br />
<br />
More details/background info at<div style="padding: 8px 0;">...</div></div></div></div><br /><div><strong>EDIT DETAILS</strong><div><div style="white-space: pre-wrap; color: #74777D;"><span style="padding: 0 2px; color: #3e6d35; background: rgba(151, 234, 151, .6);">Example files generated with these macros:<br />
<br />
KF5CoreAddons.qch (880 KB) : https://share.kde.org/index.php/s/IuaDnjh704zu5wM/download<br />
```<br />
ecm_add_qch(<br />
KF5CoreAddons_QCH<br />
OUTPUT_BASENAME KF5CoreAddons<br />
VERSION ${KF5_VERSION}<br />
ORG_DOMAIN org.kde<br />
SOURCES ${KCoreAddons_HEADERS}<br />
MD_MAINPAGE "${CMAKE_SOURCE_DIR}/README.md"<br />
LINK_QCH<br />
Qt5Core_QCH<br />
BLANK_MACROS<br />
KCOREADDONS_EXPORT<br />
TAGFILE_INSTALL_DESTINATION ${KDE_INSTALL_FULL_DATADIR}/qch<br />
QCH_INSTALL_DESTINATION ${KDE_INSTALL_FULL_DATADIR}/qch<br />
)<br />
```<br />
<br />
KF5JobWidgets.qch (208 KB) : https://share.kde.org/index.php/s/UhVPFAy2cTb8cBL/download<br />
```<br />
ecm_add_qch(<br />
KF5JobWidgets_QCH<br />
OUTPUT_BASENAME KF5JobWidgets<br />
VERSION ${KF5_VERSION}<br />
ORG_DOMAIN org.kde<br />
SOURCES ${KJobWidgets_HEADERS}<br />
MD_MAINPAGE "${CMAKE_SOURCE_DIR}/README.md"<br />
LINK_QCH<br />
KF5CoreAddons_QCH<br />
Qt5Widgets_QCH<br />
Qt5Gui_QCH<br />
Qt5Core_QCH<br />
BLANK_MACROS<br />
KJOBWIDGETS_EXPORT<br />
TAGFILE_INSTALL_DESTINATION ${KDE_INSTALL_FULL_DATADIR}/qch<br />
QCH_INSTALL_DESTINATION ${KDE_INSTALL_FULL_DATADIR}/qch<br />
)<br />
```<br />
</span></div></div></div><br /><div><strong>REVISION DETAIL</strong><div><a href="https://phabricator.kde.org/D2854" rel="noreferrer">https://phabricator.kde.org/D2854</a></div></div><br /><div><strong>EMAIL PREFERENCES</strong><div><a href="https://phabricator.kde.org/settings/panel/emailpreferences/" rel="noreferrer">https://phabricator.kde.org/settings/panel/emailpreferences/</a></div></div><br /><div><strong>To: </strong>kossebau, staniek, Frameworks<br /><strong>Cc: </strong>kfunk, staniek, winterz, ochurlaud, KDevelop<br /></div>