Important: Please read the Qt Code of Conduct - https://forum.qt.io/topic/113070/qt-code-of-conduct

Why isn't QDoc (and thus the docs) being built?



  • Hi all. After finding that examples aren't being shown in my Qt 5.15.0 build (Mac OS 10.15.5), I've been schooled on a couple of things.

    I had read that I needed to set up LLVM components and environment vars to have the doc built, which I did before building Qt. But for some reason, QDoc does not exist, and running "make docs" fails because it can't find QDoc... which the doc-building instructions say it is supposed to build: "make docs in the command line will build QDoc and the Qt 5 documentation set"

    I've verified that LLVM_INSTALL_DIR is defined correctly and points to a legit LLVM installation root directory (created by installing with Homebrew). Under that directory in /bin, llvm_config exists.

    So... what else should I look at? I've pasted the output from make docs below. Thanks!

    /qt-everywhere-src-5.15.0 % make docs
    /Applications/Xcode.app/Contents/Developer/usr/bin/make -f Makefile html_docs && /Applications/Xcode.app/Contents/Developer/usr/bin/make -f Makefile qch_docs
    /Applications/Xcode.app/Contents/Developer/usr/bin/make -f Makefile prepare_docs && /Applications/Xcode.app/Contents/Developer/usr/bin/make -f Makefile generate_docs
    cd qtbase/ && ( test -e Makefile || /qt-everywhere-src-5.15.0/qtbase/bin/qmake -o Makefile /qt-everywhere-src-5.15.0/qtbase/qtbase.pro ) && /Applications/Xcode.app/Contents/Developer/usr/bin/make -f Makefile prepare_docs
    cd src/ && ( test -e Makefile || /qt-everywhere-src-5.15.0/qtbase/bin/qmake -o Makefile /qt-everywhere-src-5.15.0/qtbase/src/src.pro ) && /Applications/Xcode.app/Contents/Developer/usr/bin/make -f Makefile prepare_docs
    cd tools/bootstrap/ && ( test -e Makefile || /qt-everywhere-src-5.15.0/qtbase/bin/qmake -o Makefile /qt-everywhere-src-5.15.0/qtbase/src/tools/bootstrap/bootstrap.pro ) && /Applications/Xcode.app/Contents/Developer/usr/bin/make -f Makefile prepare_docs
    make[5]: Nothing to be done for prepare_docs'. cd tools/moc/ && ( test -e Makefile || /qt-everywhere-src-5.15.0/qtbase/bin/qmake -o Makefile /qt-everywhere-src-5.15.0/qtbase/src/tools/moc/moc.pro ) && /Applications/Xcode.app/Contents/Developer/usr/bin/make -f Makefile prepare_docs make[5]: Nothing to be done forprepare_docs'.
    cd tools/rcc/ && ( test -e Makefile || /qt-everywhere-src-5.15.0/qtbase/bin/qmake -o Makefile /qt-everywhere-src-5.15.0/qtbase/src/tools/rcc/rcc.pro ) && /Applications/Xcode.app/Contents/Developer/usr/bin/make -f Makefile prepare_docs
    make[5]: Nothing to be done for prepare_docs'. cd tools/tracegen/ && ( test -e Makefile || /qt-everywhere-src-5.15.0/qtbase/bin/qmake -o Makefile /qt-everywhere-src-5.15.0/qtbase/src/tools/tracegen/tracegen.pro ) && /Applications/Xcode.app/Contents/Developer/usr/bin/make -f Makefile prepare_docs make[5]: Nothing to be done forprepare_docs'.
    cd 3rdparty/pcre2/ && ( test -e Makefile || /qt-everywhere-src-5.15.0/qtbase/bin/qmake -o Makefile /qt-everywhere-src-5.15.0/qtbase/src/3rdparty/pcre2/pcre2.pro ) && /Applications/Xcode.app/Contents/Developer/usr/bin/make -f Makefile prepare_docs
    /Applications/Xcode.app/Contents/Developer/usr/bin/make -f Makefile.Debug prepare_docs
    make[6]: Nothing to be done for `prepare_docs'.
    cd corelib/ && ( test -e Makefile || /qt-everywhere-src-5.15.0/qtbase/bin/qmake -o Makefile /qt-everywhere-src-5.15.0/qtbase/src/corelib/corelib.pro ) && /Applications/Xcode.app/Contents/Developer/usr/bin/make -f Makefile prepare_docs
    /Applications/Xcode.app/Contents/Developer/usr/bin/make -f Makefile.Debug prepare_docs
    /usr/local/Qt-5.15.0/bin/qtattributionsscanner /qt-everywhere-src-5.15.0/qtbase --filter QDocModule=qtcore -o /qt-everywhere-src-5.15.0/qtbase/src/corelib/codeattributions.qdoc
    /qt-everywhere-src-5.15.0/qtbase/src/corelib/qdoc_wrapper.sh -outputdir /qt-everywhere-src-5.15.0/qtbase/doc/qtcore -installdir /usr/local/Qt-5.15.0/doc /qt-everywhere-src-5.15.0/qtbase/src/corelib/doc/qtcore.qdocconf -prepare -no-link-errors -I. -Iglobal -I../3rdparty/md5 -I../3rdparty/md4 -I../3rdparty/sha3 -I../3rdparty -I../3rdparty/double-conversion/include -I../3rdparty/harfbuzz/src -I../3rdparty/forkfd -I../3rdparty/tinycbor/src -I.rcc -I../../include -I../../include/QtCore -I../../include/QtCore/5.15.0 -I../../include/QtCore/5.15.0/QtCore -I.moc/debug -I.tracegen/debug -I../3rdparty/pcre2/src -I../../mkspecs/macx-clang -I/Library/Developer/CommandLineTools/usr/include/c++/v1 -I/Library/Developer/CommandLineTools/usr/lib/clang/11.0.3/include -I/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/include -I/Library/Developer/CommandLineTools/usr/include
    /qt-everywhere-src-5.15.0/qtbase/src/corelib/qdoc_wrapper.sh: line 12: /usr/local/Qt-5.15.0/bin/qdoc: No such file or directory
    /qt-everywhere-src-5.15.0/qtbase/src/corelib/qdoc_wrapper.sh: line 12: exec: /usr/local/Qt-5.15.0/bin/qdoc: cannot execute: No such file or directory
    make[6]: *** [prepare_docs] Error 126
    make[5]: *** [debug-prepare_docs] Error 2
    make[4]: *** [sub-corelib-prepare_docs] Error 2
    make[3]: *** [sub-src-prepare_docs] Error 2
    make[2]: *** [module-qtbase-prepare_docs] Error 2
    make[1]: *** [html_docs] Error 2
    make: *** [docs] Error 2


  • Moderators

    Qt checks at configure time if it can build QDoc or not. If the check fails, then the necessary lines for building QDoc won't appear in the Makefile.

    Have a look in your build root directory for a file called configure.summary. My last build used this configuration:

    Qt Tools:
      QDoc ................................... yes
    

    If you get a no for QDoc then you must clean your build directory, re-configure, and re-build.



  • Thanks for that info. There's no configure.summary file in the source root or the Qt build-product root.

    I can't even rebuild because I don't know why the doc wasn't built in the first place (considering that I had the LLVM path exported).

    And so you're saying the documentation is wrong, where it says that QDoc will be built if you do "make docs?"


  • Moderators

    @Stokestack said in Why isn't QDoc being built?:

    There's no configure.summary file in the source root or the Qt build-product root.

    How did you configure and build Qt 5.15.0?

    And so you're saying the documentation is wrong, where it says that QDoc will be built if you do "make docs?"

    I can't say for sure as it works fine for me (on Windows) and I haven't looked at the QDoc source code in a long time.

    For now, try to build QDoc manually. Scroll down further on the wiki and you'll find these steps:

    cd qt5/qtdeclarative/src
    make sub-qmldevtools
    
    cd qt5/qttools/src
    make sub-qdoc
    


  • @JKSH I followed the steps for the Mac OS here.

    Following steps farther down the page as you suggest, I get here and it fails:

    /qt-everywhere-src-5.15.0/qttools/src % make sub-qdoc
    make: *** No rule to make target `sub-qdoc'. Stop.


  • Moderators

    @Stokestack said in Why isn't QDoc being built?:

    make: *** No rule to make target `sub-qdoc'. Stop.

    I'm guessing that your configure script decided that it can't build QDoc so it didn't put QDoc in the Makefiles, like I described before.

    I'm not sure why you didn't get a configure summary file, but you can capture it yourself:

    ./configure > config.log

    Look through the log and see what it says about QDoc.

    Note: To be safe, clean out your build directory before you run configure again. If you downloaded the source code as a zip file, delete the whole folder or extract a pristine copy of the code into a different folder. If you used git to clone the Qt repos, run this to remove all generated files:

    git clean -dfx && git submodule foreach "git clean -dfx"



  • Thanks. All I see in the log file is this:

    loaded result for config test config.qttools_qdoc.tests.libclang
    test config.qttools_qdoc.tests.libclang FAILED

    But the console output says:

    WARNING: QDoc will not be compiled, probably because libclang could not be located. This means that you cannot build the Qt documentation.

    But clang is available:

    /usr/local/opt/llvm/bin % which clang
    /usr/local/opt/llvm/bin/clang


  • Moderators

    @Stokestack said in Why isn't QDoc being built?:

    loaded result for config test config.qttools_qdoc.tests.libclang
    test config.qttools_qdoc.tests.libclang FAILED

    This test is specified at https://github.com/qt/qttools/blob/5.15.0/src/qdoc/configure.json

    I'm not 100% sure how it works or what exactly is failing in your tests, but perhaps those variable names might provide a clue.

    But the console output says:

    WARNING: QDoc will not be compiled, probably because libclang could not be located. This means that you cannot build the Qt documentation.

    But clang is available:

    /usr/local/opt/llvm/bin % which clang
    /usr/local/opt/llvm/bin/clang

    Which version? If it's version 10.0, does it help if you install an older version instead (say, v6.0.1?



  • @JKSH Thanks for that. I had searched for the "QDoc will not be compiled" string, but my search utility stupidly defaulted to excluding tons of file types.

    The Clang in the Brew-installed LLVM structure is version 10. Interestingly, the one in Xcode is version 11.

    I'm leery of downgrading it, and don't really know the proper way of going about it. configure.pri contains references up to version 9, and the only check on version numbers is to ensure that the current version is at least 3.9.0.

    Looking through the logic of this file, everything seems OK. It should be getting the correct LLVC/Clang directories from this:

       macos {
            # Default to homebrew llvm on macOS. The CLANG_VERSION test below will complain if missing.
            clangInstallDir = $$system("brew --prefix llvm")
        } else {
    

    I executed that command, and it returns the right result... BUT, the console output of configure says it's using the wrong Clang:

    Build type: macx-clang (x86_64, CPU features: cx16 mmx sse sse2 sse3 ssse3 sse4.1)
    Compiler: clang (Apple) 11.0.3

    I wonder why that is. Where does the output from the QtLog statements in qttools/src/qdoc/configure.pri go? I don't see them in the console or if I send the output of configure to a log file.


  • Moderators

    @Stokestack said in Why isn't QDoc (and thus the docs) being built?:

    The Clang in the Brew-installed LLVM structure is version 10. Interestingly, the one in Xcode is version 11.

    Interesting. LLVM 11 isn't even released yet on the official LLVM website...

    Looking through the logic of this file, everything seems OK. It should be getting the correct LLVC/Clang directories from this:

       macos {
            # Default to homebrew llvm on macOS. The CLANG_VERSION test below will complain if missing.
            clangInstallDir = $$system("brew --prefix llvm")
        } else {
    

    I executed that command, and it returns the right result... BUT, the console output of configure says it's using the wrong Clang:

    Build type: macx-clang (x86_64, CPU features: cx16 mmx sse sse2 sse3 ssse3 sse4.1)
    Compiler: clang (Apple) 11.0.3

    I wonder why that is.

    It looks like the Homebrew installation of LLVM is only used if LLVM_INSTALL_DIR is not set? The full logic is

    LLVM_INSTALL_DIR = $$clean_path($$LLVM_INSTALL_DIR)
    
    contains(QMAKE_HOST.arch, x86_64): \
    	clangInstallDir = $$replace(LLVM_INSTALL_DIR, _ARCH_, 64)
    else: \
    	clangInstallDir = $$replace(LLVM_INSTALL_DIR, _ARCH_, 32)
    isEmpty(LLVM_INSTALL_DIR) {
    	win32 {
    		return(false)
    	}
    	macos {
    		# Default to homebrew llvm on macOS. The CLANG_VERSION test below will complain if missing.
    		clangInstallDir = $$system("brew --prefix llvm")
    	} else {
    		clangInstallDir = /usr
    	}
    }
    

    Which copy of LLVM does your LLVM_INSTALL_DIR point to? What happens if you unset that variable?

    Where does the output from the QtLog statements in qttools/src/qdoc/configure.pri go? I don't see them in the console or if I send the output of configure to a log file.

    Good question. I don't know, but I would've expected it to go to stdout or stderr


Log in to reply