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

[Stokestack]

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 for prepare_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 for prepare_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

[JKSH]

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.

[Stokestack]

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?"

[JKSH]

@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

[Stokestack]

@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.

[JKSH]

@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"

[Stokestack]

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

[JKSH]

@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?

[Stokestack]

@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.

[JKSH]

@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

[Michaelis]

Is this still unresolved? I cannot build the docs either, just get "make[4]: Nothing to be done for 'prepare_docs'." all the way. No matter if i make docs or make html_docs.

And config.summary shows the following:

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

Somehow Arch manages to build the docs with the build script below. Not sure how but can it be something about the dependencies?

pkgbase=qt5-doc
pkgname=(qt5-doc qt5-examples)
_basever=5.15.8
pkgver=$_basever
pkgrel=1
arch=('any')
url='https://www.qt.io'
license=('GPL3' 'LGPL3' 'FDL' 'custom')
makedepends=('qt5-tools' 'python' 'pciutils' 'libxtst' 'libxcursor' 'libxrandr' 'libxss' 'libxcomposite' 'libxkbfile'
             'gperf' 'nss' 'clang' 'nodejs')
groups=('qt' 'qt5')
_pkgfqn="qt-everywhere-opensource-src-${pkgver}"
source=("https://download.qt.io/official_releases/qt/${pkgver%.*}/${pkgver}/single/${_pkgfqn}.tar.xz"
         qt5-webengine-python3.patch
         no-qmake.patch)
sha256sums=('776a9302c336671f9406a53bd30b8e36f825742b2ec44a57c08217bff0fa86b9'
            '398c996cb5b606695ac93645143df39e23fa67e768b09e0da6dbd37342a43f32'
            '7893df4981d6611c5aaeb4cc69bc77d14b4251842b205591a563f9a7184dfb0a')

prepare() {
  cd ${_pkgfqn/opensource-/}

  ln -s /usr/bin qttools/
  ln -s /usr/bin/{rcc,uic,moc,qmake} qtbase/bin/

  patch -d qtbase -p1 < "$srcdir"/no-qmake.patch # Use system qmake
  patch -d qtwebengine -p1 < "$srcdir"/qt5-webengine-python3.patch # Fix build with Python 3
}

build() {
  cd ${_pkgfqn/opensource-/}

  ./configure -confirm-license -opensource \
    -prefix /usr \
    -docdir /usr/share/doc/qt \
    -headerdir /usr/include/qt \
    -archdatadir /usr/lib/qt \
    -datadir /usr/share/qt \
    -sysconfdir /etc/xdg \
    -nomake examples
  make docs
}

package_qt5-doc() {
  pkgdesc='A cross-platform application and UI framework (Documentation)'
  depends=('qt5-base')

  cd ${_pkgfqn/opensource-/}
  make INSTALL_ROOT="$pkgdir" install_docs

  install -d "$pkgdir"/usr/share/licenses
  ln -s /usr/share/licenses/qt5-base "$pkgdir"/usr/share/licenses/${pkgname}
}

package_qt5-examples() {
  pkgdesc='Examples and demos from qt5 documentation'
  depends=('qt5-doc')

  _base="$pkgdir"/usr/share/doc/qt/examples

  # The various example dirs have conflicting .pro files, but
  # QtCreator requires them to be in the same top-level directory.
  # Matching the Qt5 installer, only the qtbase project is kept.
  mkdir -p $_base
  cp ${_pkgfqn/opensource-/}/qtbase/examples/examples.pro $_base

  _fdirs=$(find "${_pkgfqn/opensource-/}" -maxdepth 2 -type d -name examples)
  for _dir in $_fdirs; do
      _mod=$(basename ${_dir%/examples})

      if [ -e "$_dir/README" ]; then
        cp $_dir/README $_dir/README.$_mod
      fi

#     mkdir $_base/$_mod
      cp -rn $_dir/* $_base
  done
}