Doxygen failed to run html help compiler, hhc.exe error HHC5010 when running from folder that has a parent folder that starts with "."

Question

I am using Conan package manager on Windows to create a package. The conan command to create the package copies files to a folder within %USERPROFILE%\.conan (or C:\Users\xxxxxxx\.conan). Then from this location it builds a Visual Studio project and ultimately calls doxygen.exe to create a .chm help file in a post-build command. The doxygen command fails with:

error : failed to run html help compiler on index.hhp

Further investigation reveals the hhc.exe command executed by doxygen is failing with:

C:\Users\xxxxxxx\.conan\data\Module\1.0.0\user\channel\build\524dc97e4a3dd1f774ea3897f9e4faf26c5457d2\Documentation>"C:/Program Files (x86)/HTML Help Workshop/hhc.exe" html\index.hhp

HHC5010: Error: Cannot open "C:\Users\xxxxxxx\data\Module\1.0.0\user\channel\build\524dc97e4a3dd1f774ea3897f9e4faf26c5457d2\Documentation\html\Module.chm". Compilation stopped.

Close inspection reveals that in the error message, the ".conan" folder is missing. Sure enough, I confirmed that hhc.exe fails when the index.hpp resides in a folder that has a parent folder that starts with a ".".

Attempts to resolve this:

• changing the Doxyfile setting OUTPUT_DIRECTORY to "$(TMP)/DoxygenModule" resolves the error, but creates the .chm file in another location, which I do not prefer.
• navigating to the 8DOT3 name of the ".conan" folder, which is "CONAN~1", to run the hhc.exe command, succeeds, but unfortunately I have no way of getting conan to use this 8DOT3 path for creating the package. E.g. C:\Users\xxxxxxx\CONAN~1\...

I can live with the using the %TMP% folder but would prefer generating the .chm in the current folder. Anyone have any ideas?

HTML Help Workshop v1.31 is installed on my machine at C:\Program Files (x86)\HTML Help Workshop, probably from a Visual Studio installation (not sure). I attempted using a version downloaded from Microsoft website (v1.30) as well, which made no difference.

Other info: Conan version 1.18.0, Doxygen version 1.8.14, Windows 10 Version 1809

Answer 1

Unfortunately not a solution, but this is a known limitation in the hhc.exe, see: https://social.msdn.microsoft.com/Forums/en-US/0681145c-223b-498c-b7bf-be83209cbf4e/issue-with-html-workshop-in-a-windows-container?forum=visualstudiogeneral

HTML Help 1.x command line compiler hhc.exe cannot compile CHM file to folder whose full path contains folder name starting with dot. If you have that problem, you probably specified output path with folder starting with dot, e.g. "d:\My files.NET\documentation". You can use dots in folder names but not at the beginning.

Edit 2019-11-15: I've just pushed a proposed patch to github (pull request 7402, https://github.com/doxygen/doxygen/pull/7402). This proposed patch changes inside doxygen from the current directory to the short named current directory, but just for the HTML Help compilation.

Edit 2019-11-16: Code has been integrated in the master version on github.

Answer 2

This is not an answer either. Actually, you found the answer and workaround[s] yourself.

Use OUTPUT_DIRECTORY to specify a directory containing no folder names beginning with periods.

The error you described is a known issue of the MS HTML Help compiler. More general, the HTML Help compiler does not like some folder and file names. Try and stick with these characters _, a..z, A..Z, 0..9. Do not use these signs in particular ., -, # .

Please note that the proprietary CHM file format is about 20 years old (Windows 95, ...). HTML Help is in maintenance mode, which means no new features and bug fixes are expected for either the runtime or the compiler. All mainstream development on HH has stopped.

There is no way to avoid this error if a directory name above begins with a period. Not even if only the necessary files are written by Doxygen and compiling of the index.hhp is done by a third-party tool like FAR HTML using your path that contains .conan. This is because all applications are using the faulty HHA.dll.

The above applies of course to the entire workflow you have described. Maybe you can interrupt it.

• Doxygen can be configured not to call the HTMLHelp compiler. Just uncheck the GENERATE_HTMLHELP option (DoxyWizard: Experts > Topics > HTML). You have all files generated by Doxygen in your preferred output directory - but of course without the CHM file. This can be imported later e.g. by HelpNDoc and compiled as a CHM file in another location.

• If you can interrupt the workflow and can also make changes to Doxygen's settings, then a preference setting of OUTPUT_DIRECTORY to e.g. C:/CacheMenu/CONAN~1/DOXYGE~1 also works as expected (here used as test case).

No matter what you do, your workaround and copy and paste from another directory outside is a quick solution at this stage. Please note the EDIT in @albert's answer.