Congratulations to our 2022 Qt Champions!

QHelpEngine and Sqlite deployment problems on a Mac

  • I recently ported my opensource application to Max OS X.
    Thanks to Qt I now have it running on Linux, Windows and OS X with minimal changes.

    I am however having one problem that I am tearing my hair out about and don't know how to resolve. I use QHelpEngine to display the help text which requires Sqlite for the contents and index.

    The development version works correctly, the help window correctly populates the contents and index widgets.

    The distribution packager uses macdeployqt to add the Qt dependencies. Afterwhich installing the package into the Applictions folder on my development machine also functions correctly.

    However, when other users install the application, the contents and index widgets are blank. Clearly, something that should be deployed is not being deployed but I can't seem to figure out what. QHelpEngine just fails silently without any messages even with a debug build.
    Qt is installed to /usr/local/opt/qt which is a link to /usr/local/Cellar/qt I have tried renaming /usr/local/Cellar/qt to /usr/local/Cellar/XX to hide my development library but help still functions correctly on my development system but no where else.

    Any help will be much appreciated - I should mention that I have minimal Mac knowledge, neither as a user or a developer, and that I am developing on a cloud based virtual machine - VNC is extremely slow!


  • Ok, I am still battling to solve what should be a relatively simple problem which is preventing me from releasing an otherwise fully functional Mac version of my application.

    This is so incredibly frustrating - it took a day or two to get 50,000 lines of code up and running on the Mac with everything working, except for the Help Window Contents and Index tabs.

    And without the Help Content tab, Help is unusable, and without Help, the application is pretty much unusable as well.

    Surely I am not the only person to have tried to install a Mac version of an application using QHelpEngine ?

    To try and duplicate the problem I did a completely clean install of Mac OSX 10.14.6 the first thing I did after install, was to download and install my application, the exact same package the other testers have been using.

    I was completely surprised to find that the Contents and Index tabs were populated correctly, yet on 8 out of 12 test machines (most running 10.14.6), these remain blank!

    Not having access to the test machines - various people around the world who offered to test the application - I am at a loss as to how to fix the problem.

    Any tips as to what could be the cause of or even how to duplicate the problem would be very much appreciated.

  • Lifetime Qt Champion

    Hi and welcome to devnet,

    Can you provide a minimal compilable example that shows that behaviour ?

    What version of Qt are you using ?

  • Hi @sgaist, thank you.

    I am running Qt 5.13.0 installed using: brew install qt
    As far as I can tell from using the env command it doesn't set any environment variables.

    I have been doing some experimentation that might offer some clues to the problem.

    After building, my build script copies the two help files AlbumEasy.qch and AlbumEasy.qhc into the newly build application folder:

    Running the app from the command line, it behaves correctly:

    I then include the Qt redistributables :

    Running from the command line it still behaves correctly.

    The application is then packaged using pkgbuild

    The package is used to install the application to the Applications directory.

    Running the application from the Applications directory, whether by double-clicking in Finder or from the command line:
    incorrectly displays a blank Help Contents and a blank Index tab.

    However, copying the application directory to my home directory:
    cp -rf /Applications/ .
    displays correctly when run:

    So, to cut a long story short, the problem only seems to manifest when run from the version installed to the /Applications directory.
    I can only assume then that it is picking up an incorrect version of one of the libraries or plugins somewhere on the system, but I am not sure how or where as no Qt related environment variables appear to be set.

    Any help would very much be appreciated, I haven't yet had a chance to try and create a minimal version, but will do so if necessary.


  • Running the application from the Application folder as root using sudo it performed correctly.
    Afterwhich I noticed that the last-modified date of the .qhc help file had been updated.
    It turns out that the user needs to have write permission on this file.

    So this "deployment" problem that I wasted countless hours on thinking it has to do with plugins or shared libraries has nothing actually to do with deployment, it is simply a case of:

    QHelpEngine REQUIRES WRITE PERMISSION on the .qhc file (shouting for the benefit of anyone who may stumble across this thread in the future with the same problem).

    This is not documented anywhere as afar as I can tell, it does not generate any warnings or error messages, nor is the QHelpEngine::warning() signal triggered, all that happens is that it fails silently. The only symptom is a blank Help Contents/Index.

    I have no idea why QHelpEngine needs to write to the file, I could probably delve into the library source to discover why, but I have spent far too much time on this problem already. If anyone knows, please update this thread, afterwhich I will mark it as solved.

  • Lifetime Qt Champion

    That's a bit surprising indeed...

    Did you check the bug report system for something related ?

  • @sgaist
    I could probably have saved myself a ton of time if I had of checked the bug reporting system -
    Closed as fixed in 5.12.1 it would seem that the fix did not propagate through to 5.13.0

    I was looking to reopen the bug, but that does not seem possible. I am not too familiar with Jira but it seems that I will have to create a new issue and hopefully link it to the closed report.

  • Lifetime Qt Champion

    Can you check with Qt 5.13.1 ?
    In any case you can still comment on the bug page that you have another case where it's not working.

  • @sgaist
    Checking on 5.13.1 is a little difficult for me as I don't actually have access to a Mac, I am working on a cloud based virtual Mac - VNC is incredibly slow, although I do compiling and building using SSH.

    More of an issue is having someone test it. It does not fail consistently, a few people have been trying out the application, but not all of them are experiencing the problem, and the ones that do, are getting a little tired of me sending them new builds to try.

    I will add a comment to the Jira, I presume that the assignee will get the comment?

  • Lifetime Qt Champion

    Yes, all persons watching as well as the assignee will get your comment.

    As for the people who are experiencing that issue, did you gather their environment information to see if there's a pattern ?

  • @sgaist
    There does not seem to be any discernible environment-related reason as to why this happens on some systems and not others.

    I have created a new bug report