Build with -DREBUILD_MANUAL fails on Debian Unstable

[Felix Krull]

Building with -DREBUILD_MANUAL fails on Debian Unstable (and probably other recent Linux distributions) with the following error:

$ cmake ../speedcrunch/src/ -DREBUILD_MANUAL=on
$ make
...
Scanning dependencies of target speedcrunch_arcc_manual
make[2]: *** No rule to make target 'doc/manual.qrc', needed by 'CMakeFiles/speedcrunch_arcc_manual'.  Stop.
make[1]: *** [CMakeFiles/Makefile2:456: CMakeFiles/speedcrunch_arcc_manual.dir/all] Error 2
make: *** [Makefile:163: all] Error 2

I suspect this is the consequence of some change either in CMake or in Qt or in the Qt-CMake integration.

See also https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=897531

---

It feels like this part -- rebuilding the manual during the build -- has caused so many problems. I'll probably just take it out. Rebuilding the manual is still important for the Debian package, but splitting the process should make it more robust:

• Run some command(s) to build the manual in a separate directory, probably based on the existing CMakeLists.txt in the docs folder.
• Run the main build and specify the path to the rebuilt manual.

[Helder Correia]

@fk Why do we need to rebuild the manual for Debian? Don't we ship a prebuilt in the sources?

[Felix Krull]

@heldercorreia You know, I couldn't actually find a reference to this "you must rebuild everything from sources" rule I had imagined Debian had. The closest is this wiki entry which sounds more like a strong recommendation than a rule.

But in general: the prebuilt HTML docs are also build artifacts like binaries, so it's at least recommended to rebuild them during the Debian package build process. This ensures that the binary package doesn't contain binaries that aren't available in source form.

[Helder Correia]

Well, they clearly ARE available in source form.

[Felix Krull]

Sure. Let me rephrase: I don't really intend to break with Debian best practices here. And those encourage rebuilding everything from source that you can, which includes the docs.

[Helder Correia]

The docs could have been written by hand. The fact that we use a pre-language to generate them is a minor detail. We're talking about hypertext documentation here, not exploitable executables. This policy enters the paranoid field.

[Tey']

Might be wrong, but from the build log, it seems the problem is related to parallel compilation (manual.qrc is needed before it is generated):

make -f CMakeFiles/testdmath_autogen.dir/build.make CMakeFiles/testdmath_autogen.dir/build
make[4]: *** No rule to make target 'doc/manual.qrc', needed by 'CMakeFiles/speedcrunch_arcc_manual'.  Stop.
make[3]: *** [CMakeFiles/Makefile2:456: CMakeFiles/speedcrunch_arcc_manual.dir/all] Error 2
make[3]: *** Waiting for unfinished jobs....
(...)
[  2%] Generating manual.qrc
make[4]: Leaving directory '/<<PKGBUILDDIR>>/obj-x86_64-linux-gnu'
make[4]: Entering directory '/<<PKGBUILDDIR>>/obj-x86_64-linux-gnu'

@fk Did you try without launching make with -j8?

[Felix Krull]

@Teyut It's an ordering issue of dependencies, yes, but I can reproduce it without any -j. Running make a second time works; but neither of those are particularly good solutions.

@heldercorreia It's not about exploitability, it's about free software reasons. The HTML docs could have been written by hand, yes. But they weren't. They were generated from the reStructuredText files, which makes those the source and the HTML docs the compilation result. I've seen the term "preferred format for modification" or somesuch used for this -- if someone wants to modify the documentation, they shouldn't edit the HTML docs directly, they should edit the source and rebuild the HTML docs.

The DFSG requires (for things in main) that the source is available, which they take very seriously. Not using prebuilt bits makes it easy to show that the source for everything that ends up in the archive is in the source package.

[Felix Krull]

Oh right, I did remove the problematic part.