New: ECMAddQch, for generating qch & doxygen tag files
ClosedPublic

Authored by kossebau on Sep 25 2016, 11:06 PM.

Details

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 inter-QCH linking is especially useful for libraries extending Qt,
where many of the used types are from Qt libraries. The macros
come with the needed information for Qt libraries prepared, so the
used Qt libraries just need to be listed in the LINK_QCHS argument
by target names, like Qt5Core_QCH or Qt5Widgets_QCH.

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
to add them to the default help file collection.
The QCHDIR variant would provide a neutral, but central installation location.
Neutral, as it never "pollutes" the Qt system dirs with files possibly unrelated to
Qt-based development (e.g. when simply using qthelp tools for documentation),
and central, to help with finding available QCH files for manually adding/loading
them into a viewer, given there is no official way currently to register the availability of
QCH files on installing.

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:

More details/background info at
https://frinring.wordpress.com/2016/09/27/adding-api-dox-generation-to-the-build-by-cmake-macros/

Test Plan

Example files generated with these macros:

KF5CoreAddons.qch: https://share.kde.org/index.php/s/IuaDnjh704zu5wM

ecm_add_qch(
    KF5CoreAddons_QCH
    NAME KCoreAddons
    BASE_NAME KF5CoreAddons
    VERSION ${KF5_VERSION}
    ORG_DOMAIN org.kde
    SOURCES ${KCoreAddons_HEADERS}
    MD_MAINPAGE "${CMAKE_SOURCE_DIR}/README.md"
    LINK_QCHS
        Qt5Core_QCH
    BLANK_MACROS
        KCOREADDONS_EXPORT
        KCOREADDONS_DEPRECATED
        KCOREADDONS_DEPRECATED_EXPORT
    TAGFILE_INSTALL_DESTINATION ${KDE_INSTALL_QTQCHDIR}
    QCH_INSTALL_DESTINATION ${KDE_INSTALL_QTQCHDIR}
    COMPONENT Devel
)

KF5JobWidgets.qch: https://share.kde.org/index.php/s/UhVPFAy2cTb8cBL

ecm_add_qch(
    KF5JobWidgets_QCH
    NAME KJobWidgets
    BASE_NAME KF5JobWidgets
    VERSION ${KF5_VERSION}
    ORG_DOMAIN org.kde
    SOURCES ${KJobWidgets_HEADERS}
    MD_MAINPAGE "${CMAKE_SOURCE_DIR}/README.md"
    LINK_QCHS
        KF5CoreAddons_QCH
        Qt5Widgets_QCH
        Qt5Gui_QCH
        Qt5Core_QCH
    BLANK_MACROS
        KJOBWIDGETS_EXPORT
    TAGFILE_INSTALL_DESTINATION ${KDE_INSTALL_QTQCHDIR}
    QCH_INSTALL_DESTINATION ${KDE_INSTALL_QTQCHDIR}
    COMPONENT Devel
)

Diff Detail

Repository
R240 Extra CMake Modules
Branch
addApiDox
Lint
No Linters Available
Unit
No Unit Test Coverage
kossebau updated this revision to Diff 6917.Sep 25 2016, 11:06 PM
kossebau retitled this revision from to New: ECMGenerateApiDox, for generating qch & tag files.
kossebau updated this object.
kossebau added subscribers: Frameworks, KDevelop, ochurlaud.
kossebau updated this object.Sep 25 2016, 11:24 PM
kossebau updated this revision to Diff 6927.Sep 26 2016, 4:57 PM

Fix generated inter-qch links, add support for unversioned namespace

kossebau updated this object.Sep 26 2016, 4:58 PM
kossebau updated this revision to Diff 6941.Sep 27 2016, 5:04 AM

Fixing value of exported ${name}_APIDOX_TAGSFILE & tiny improvements

kossebau updated this object.Sep 27 2016, 3:54 PM
staniek edited edge metadata.

Added myself as reviewer, let's use Reviewers field so that people can see what's todo on the Phab home page.

kossebau updated this revision to Diff 6979.Sep 28 2016, 11:33 PM
kossebau edited edge metadata.

Add alternative SOURCES, add IMAGE_DIRS, improve status messages

kossebau updated this revision to Diff 6993.Sep 29 2016, 4:23 PM

Add support for multiple qch in same build, example dir, MD mainpage

kfunk added a subscriber: kfunk.Nov 17 2016, 10:47 PM

Heya Friedrich. You asked me to review this.

From a super brief scan of the code I don't see anything blatantly wrong. I trust you that you've tested this good enough. Love the extensive documentation.

What's left here from your side?

kossebau updated this revision to Diff 8348.Nov 21 2016, 4:34 PM

Rename methods apidox->qch, use targets instead of pattern vars, more apidox

kossebau retitled this revision from New: ECMGenerateApiDox, for generating qch & tag files to New: ECMAddQCH, for generating qch & doxygen tag files.Nov 21 2016, 5:25 PM
kossebau updated this object.
kossebau edited the test plan for this revision. (Show Details)
kossebau added a reviewer: Frameworks.
kossebau removed a subscriber: Frameworks.

a) recommended install path for qch and tag files?

At least when KDE_INSTALL_USE_QT_SYS_PATHS is TRUE, one could use QT_INSTALL_DOCS (via ECMQueryQmake) var.

kossebau updated this revision to Diff 8364.Nov 22 2016, 12:14 AM
kossebau edited the test plan for this revision. (Show Details)

Small fixes

a) recommended install path for qch and tag files?

At least when KDE_INSTALL_USE_QT_SYS_PATHS is TRUE, one could use QT_INSTALL_DOCS (via ECMQueryQmake) var.

Good proposal, I think I should go for that for now.
Because installing to QT_INSTALL_DOCS would solve the issue of discoverability, as e.g. Qt Assistant automatically picks up QCH files added there. IMHO if someone installs a package with a QCH file (especially for a Qt-based lib), it should be automatically included by the doc viewers and not need the user to also manually having to add it manually by searching the file in the system folders frst (so opt-out instead of opt-in).

kossebau updated this revision to Diff 8485.Nov 24 2016, 10:31 PM

Add QTQCHDIR and QCHDIR to KDEInstallDirs

kossebau updated this object.Nov 24 2016, 10:50 PM
kossebau edited the test plan for this revision. (Show Details)
kossebau edited the test plan for this revision. (Show Details)
kossebau updated this revision to Diff 8586.Nov 29 2016, 1:32 AM

integrate feedback from review with use for kdb, kproperty & kreport

kossebau edited the test plan for this revision. (Show Details)Nov 29 2016, 1:46 AM
kossebau updated this revision to Diff 8635.Nov 30 2016, 3:53 PM

Use rather subfolder doc/QCH for installing QCH files

shumski added inline comments.Nov 30 2016, 4:09 PM
kde-modules/KDEInstallDirs.cmake
534

I think e.g. QMLDIR, PLUGINDIR, ECM_MKSPECS_INSTALL_DIR, etc. are vanilla Qt's. QCH files are thus installed straight into QT_INSTALL_DOCS dir AFAICS ...

kossebau added inline comments.Nov 30 2016, 4:23 PM
kde-modules/KDEInstallDirs.cmake
534

Not sure what you mean, please point out the issue you see here with more details :)

The plan here is:
if KDE_INSTALL_USE_QT_SYS_PATHS is set, install QCH files to QT_INSTALL_DOCS, if not, some "normal" dir (there is no standard dir for QCH in general currently, everybody installs their 3rd-party QCH files somewhere).
See thread http://lists.qt-project.org/pipermail/development/2016-November/027856.html and especially the latest http://lists.qt-project.org/pipermail/development/2016-November/028001.html
Feedback is very welcome.

kossebau updated this revision to Diff 8639.Nov 30 2016, 4:26 PM

adapt also documentation to doc/QCH

shumski added inline comments.Nov 30 2016, 4:28 PM
kde-modules/KDEInstallDirs.cmake
534

I mean, addition of qch subdir is 'your' invention here.
If Frameworks were to use only qmake build-system, i'm sure qch files would end up in QT_INSTALL_DOCS directory.
I.e. for KDE_INSTALL_USE_QT_SYS_PATHS=ON the paths are Qt's, so are with KDE_INSTALL_USE_QT_SYS_PATHS=OFF, just that for the latter case they are read from sources, opposed to querying qmake.

kossebau added inline comments.Nov 30 2016, 4:57 PM
kde-modules/KDEInstallDirs.cmake
534

But that is the same for the current QTPLUGINDIR, QTQUICKIMPORTSDIR, & QMLDIR, no? They also only get set to the Qt system paths if KDE_INSTALL_USE_QT_SYS_PATHS=ON, otherwise get set to something based on general LIBDIR.
(I would have liked to put the setting of QTQCHDIR next to these other ones, but at that time DATAROOTDIR is not yet defined, so had to create a separate if-else)
And especially if installing multiple versions of the same dir (e.g. for different projects or as developer of the lib), it will be needed to optionally not install into the Qt system path, but point all the tools via ENV variables or other ways to the matching plugins or documentation.

shumski added inline comments.Nov 30 2016, 5:22 PM
kde-modules/KDEInstallDirs.cmake
534

Right. But if you install a framework to same prefix as Qt, you get free recognition of plugins, qml imports, etc... This is valid for both /usr and custom prefix installs.
I guess what i want to say is that there is IMHO no reason this should also not work for QCH docs.

kossebau added inline comments.Nov 30 2016, 6:26 PM
kde-modules/KDEInstallDirs.cmake
534

But isn't this free recognition happening via KDE_INSTALL_USE_QT_SYS_PATHS as well?
At least this is how I understand https://cgit.kde.org/extra-cmake-modules.git/tree/kde-modules/KDEInstallDirs.cmake#n442 to work.
This is also what I rely on, as I agree that it should also happen when installing to the same prefix :)

shumski added inline comments.Nov 30 2016, 6:52 PM
kde-modules/KDEInstallDirs.cmake
534

It is :) But with this latest revision it is not when that var is off =) I'm saying that for both cases it should happen.

kossebau added inline comments.Nov 30 2016, 7:17 PM
kde-modules/KDEInstallDirs.cmake
534

Fear I am still missing what you mean. So let's go explicitely, here is what I understand to happen:

There are six different cases when using this macro and on the first invocation of cmake, from the combinations of installing to a different prefix or the same prefix as Qt (2 variants) versus KDE_INSTALL_USE_QT_SYS_PATHS being not set/defined, set to ON, set to OFF (3 variants).

In these 3 cases plugins, QCH & Co. will be all installed to Qt system dirs and thus automatically picked up by Qt, without the need for further env var settings:

  • -DKDE_INSTALL_USE_QT_SYS_PATHS=ON, different prefix
  • -DKDE_INSTALL_USE_QT_SYS_PATHS=ON, same prefix
  • KDE_INSTALL_USE_QT_SYS_PATHS not passed as argument, same prefix (so

In the three other cases plugins, QCH & Co will be installed in dirs and need further env var settings, for Qt (and Qt Assistant) to also pick up the stuff.

Where do we see things differently? And just to make sure, you have seen the right lines at the link I passed before, how _default_KDE_INSTALL_USE_QT_SYS_PATHS is set to ON if the same prefix is used?

shumski added inline comments.Nov 30 2016, 9:44 PM
kde-modules/KDEInstallDirs.cmake
534

Hm, i guess i haven't checked KDEInstallDirs in a while. Somehow i remember KDE_INSTALL_USE_QT_SYS_PATHS was only activated by default if CMAKE_INSTALL_PREFIX was /usr.

Ok, so the non-recognition part should not happen that often -> I'm assuming qch files are looked up as QLibraryInfo::DocumentationPath (so, QT_INSTALL_DOCS) + *qch.

So with your path, they will not be found (yeah with different prefix they aren0t still found, but with qch/ subdir user needs one additional envar for KF5 qch's - imagine you need to export QT_PLUGIN_PATH for Qt plugins, and one more path for KF5 plugins).
I don't see a reason to append qch subdir to installation location -> as if you're intentionally hiding those files ;-)

kossebau updated this revision to Diff 8783.Dec 5 2016, 6:12 PM

s/QCH/Qch/, use find_oackage for needed tools, more control over output

kossebau retitled this revision from New: ECMAddQCH, for generating qch & doxygen tag files to New: ECMAddQch, for generating qch & doxygen tag files.Dec 5 2016, 6:23 PM
kossebau updated this object.
kossebau edited the test plan for this revision. (Show Details)
kossebau updated this object.Dec 6 2016, 2:26 PM
kossebau added inline comments.Dec 6 2016, 3:12 PM
kde-modules/KDEInstallDirs.cmake
534

Any chance you perhaps misread the code? Because what you say does not match what should happen at least by what I intended by the code (and what it does on testing) :)

The qch/ subdir is used with the non-QT_INSTALL_DOCS installation directory. So _define_relative(QTQCHDIR DATAROOTDIR "doc/qch") would be e.g. "/usr/share/doc/qch" when installing to prefix /usr. Both this and "/usr/share/doc" will never result in Qt Assistant automatically adding the QCH file to the default help file collection. This only happens when installing directly into QT_INSTALL_DOCS (undocumented feature, but stable for some time :) ).

In the branch which sets up QTQCHDIR to be the Qt system dir, _define_absolute(QTQCHDIR ${qt_docs_dir}) will result in QTQCHDIR being equal to QT_INSTALL_DOCS. No /qch subdir here.

kossebau updated this revision to Diff 8856.Dec 8 2016, 3:39 PM

support inheriting LINK_QCHS, drop LINK_QCHS_VERSIONED for now

kossebau updated this object.Dec 8 2016, 3:40 PM
kossebau updated this revision to Diff 8863.Dec 8 2016, 6:22 PM

lowercase virtual folder name for consistency with the Qt ones

kossebau updated this revision to Diff 14671.May 18 2017, 1:38 PM

Some minor improvements, prepare for release with 5.36

Restricted Application added projects: Frameworks, Build System. · View Herald TranscriptMay 18 2017, 1:38 PM
kossebau edited the summary of this revision. (Show Details)May 18 2017, 1:44 PM
kossebau edited the test plan for this revision. (Show Details)
kossebau updated this revision to Diff 14672.May 18 2017, 1:48 PM

fix lett old "since 5.30"

If there are no further comments or other feedback, I would like to commit this once 5.35 is tagged.

This revision was automatically updated to reflect the committed changes.