Application deployment with assistant as help viewer

[jml]

I am using assistant as a custom help viewer for my application, and it works fine on my machine with Qt installed. But I can't find anything in the Qt documentation about how to deploy asistant along with my application and my .qhc file to another target machine. Thanks for any help.

[jml]

I managed to get assistant with all its dependencies to run on the target machine. EXCEPT, it now gives me the error message

"The specified collection file coud not be read!"

with no additional information.

I should say that I'm developing on Windows/XP, VS2005 with Qt 4.4.1 commercial addition.

If, on the target machine, I do this from the command prompt

assistant -collectionFile foo.qhc

assistant -collectionFile foo.qhc

To copy to clipboard, switch view to plain text mode 

I get the above error message. The very same help collection file works fine on my development machine.

Due to the under-whelming response to my initial post, I have no great expectations for any help here on this forum. But it is very frustrating that the QT documentation touts this new and improved assistant as a custom help tool, but says absolutely nothing about how to deploy it to a target machine, and evidently the QT employee(s) who monitor these forums have no knowledge either.

[jacek]

evidently the QT employee(s) who monitor these forums have no knowledge either.

Qt Centre is not "monitored" by any company employees. It is run solely by volunteers. If you want help from Nokia's Qt Software division, contact the support.

[jml]

Well, after much conversation with Qt support, and my own sleuthing, I finally got my application to deploy successfully with assistant as a custom help viewer. For anyone interested, you need to know:

1. The help collection file (.qhc) is an sqlite database. You need to ship
%QTDIR%/plugins/sqldrivers/qsqlite4.dll with your application, AND it must be in the subdirectory sqldrivers. As far as the subdirectory goes, maybe it's possible to change that with qt.conf, but I don't know how.

2. It was my impression the .qhc file had everything needed for deployment, though I don't think the QtHelp documentation says explicitly. But you also need to ship the .qch files - the intermediate files that are the output from qhelpgenerator and the input to qcollectiongenerator.


I hope this saves someone the grief that I went through to get this to work. My impression is that QtHelp, being a new feature in Qt, isn't quite ready for prime time - at least the documentation of it isn't. Hopefully that will change in future releases.

[jml]

Well, I've since upgraded to Qt4.4.2, and the advice in my previous post no longer works. The assistant simply exits with no error message and does nothing. .

For all those who are considering using assistant as a custom stand-alone help viewer for applications, I have this word of advice: DON'T!!!.

I'm very disappointed in Qt for documenting this as an option but not supporting it. I wish I had not gone down this path.

[wysota]

As far as I know this works quite fine so you must be having some deployment problems. Is your Qt taken from some binary package distribution or did you compile it yourself? What exactly happens, have you tried debugging?

[jml]

I'm using a binary distribution - I did not compile it myself.

I'm not sure how I would go about debugging it. It's the application.exe that is not functioning - not my application.

I have two versions of my application deployed on my machine - the same one I'm developing on running Vista, developing with Visual Studio 2005. I'm running the assistant from the command line (cygwin). Version 1 of my application was built using Qt 4.1.x, version 2 was built using Qt 4.4.2

In the command line, if I go to C:\Program Files\myAppVersion1 and run
> ./assistant -collectionFile myHelp.qhc
it brings up the assistant with my help files just fine.

But, if I set my current directory to C:\Program Files\myAppVersion2 and enter the same command, it returns to the command prompt and nothing happens.

In both directories, if I leave out the "./" so that it runs the installed assistant in
C:\Qt\4.4.2\bin, it works fine. I actually copied every .dll file from c:\Q\4.4.2\bin into the deployment directory under "Program Files" and still nothing happens.

[wysota]

I'm not sure how I would go about debugging it. It's the application.exe that is not functioning - not my application.

We usually debug executable files

Try running assistant under gdb (or whatever other debugger you use) and when it crashes (it crashes, right?), check the backtrace to see where it crashes. Just make sure you are using a debug-enabled version of assistant.

But, if I set my current directory to C:\Program Files\myAppVersion2 and enter the same command, it returns to the command prompt and nothing happens.

Maybe it simply can't find the help collection file?

In both directories, if I leave out the "./" so that it runs the installed assistant in
C:\Qt\4.4.2\bin, it works fine. I actually copied every .dll file from c:\Q\4.4.2\bin into the deployment directory under "Program Files" and still nothing happens.

Did you copy the sqlite driver to the sqldrivers subdirectory of the directory Qt searches for plugins (like the current directory or any directory defined in qt.conf file)? Does assistant work if you tell it to use one of the default help collections?

[jml]

We usually debug executable files

What I meant to say is that assistant.exe is crashing, not my application.

Try running assistant under gdb (or whatever other debugger you use) and when it crashes (it crashes, right?), check the backtrace to see where it crashes. Just make sure you are using a debug-enabled version of assistant.

I don't see that I have a debug-enabled version of assistant. I'm guessing I need to download the source and compile it.

And no, it is not crashing, is simply exits with nothing happening - no error messages. nothing.

Maybe it simply can't find the help collection file?

The collection file exists in the deployment directory in both cases, no difference.

Did you copy the sqlite driver to the sqldrivers subdirectory of the directory Qt searches for plugins (like the current directory or any directory defined in qt.conf file)? Does assistant work if you tell it to use one of the default help collections?

Yes. it took a long while to figure this out through trial and error with the version 1 of my application . I did not see this anywhere in the documentation, nor did Qt support help me with this, which is one reason you are seeing a lot of frustration coming through in my posts.

[jml]

Does assistant work if you tell it to use one of the default help collections?

I just tried

./assistant -collectionFile c:/Qt/4.4.2/examples/help/simpletextviewer/documentation/simpletextviewer.qhc

with the same result - nothing happens. assistant exits with no messages. Again, if I drop the "./" at the beginning so that it uses the installed assistant, it works as expected, bringing up the simpletextviewer help window.

[wysota]

Use some dependency walker (like depends.exe) to check if you have all dependencies filled. In addtion make sure the sqldrivers folder exists in the directory with your assistant binary and that it contains sqlite driver library.

[jml]

Use some dependency walker (like depends.exe) to check if you have all dependencies filled. In addtion make sure the sqldrivers folder exists in the directory with your assistant binary and that it contains sqlite driver library.

I've done all that. I actually went back and compared the dependencies between the assistant that works (from Qt 4.1.3) and the one that does not (from Qt 4.4.2), and they appear to be identical.

Also, if I copy assistent.exe, along with all the DLLs from my version 1 deployment (bulit with Qt 4.1.3) directory to my version 2 directory it works with the .qhc and .qch file I created with Qt 4.4.2

[wysota]

I'd really use a debugger if I were in your situation

[jml]

Well, I guess there is a partial "mea culpa" is in order here.

As I was looking at the dll files included in my Visual Studio deployment project, I noticed that the QtCore4.dll and QtGui4.dll files were being pulled from my Miktex installation on my machine, not the Qt directory. A Visual Studio deployment project automatically includes dependencies that the application requires - in this case QtCore4.dll and QtGui4.dll. But since the MikTex was higher up in the PATH hierarchy on my computer, it pulled these files form MikTex instead of my Qt installation.

So, a warning to everyone setting up a deployment project: Make sure the Qt-related dll files being deployed are the right ones!

I say partial mea-culpa because my initial complaint still stands: Qt documentation does not include adequate information about deploying the assistant; it fails to mention the need for the sqldrivers directory with the Qtsqlite4.dll (or whatever it's called), and the need for both the .qhc and the .qch file. I must say that the reason I'm disappointed is that I have found Qt documentation to be quite good in almost every other aspect of Qt that I worked with, so I find the inadequacy in this area to be surprising and thus disappointing.

[wysota]

I say partial mea-culpa because my initial complaint still stands: Qt documentation does not include adequate information about deploying the assistant; it fails to mention the need for the sqldrivers directory with the Qtsqlite4.dll (or whatever it's called), and the need for both the .qhc and the .qch file.

Well... yeah, it also doesn't mention you need a computer for this. I think qch file is embedded into qhc file (I'm not sure though) and it is described in the docs, step by step. I know, I was building a standalone help collection two days ago using that documentation. Is there a chance you just missed the tutorial?

[jml]

Well... yeah, it also doesn't mention you need a computer for this.

Wysota, that's a cheap shot. You make it sound that any idiot should just know that assistant requires the sqldrivers with sqlite3. But I guess it's just a second nature to a brilliant guru like yourself.

I think qch file is embedded into qch file (I'm not sure though)

huh?

and it is described in the docs, step by step. I know, I was building a standalone help collection two days ago using that documentation. Is there a chance you just missed the tutorial?

What tutorial would that be? I have read and re-read the documentation shipped with Qt, via the Qt assistant, in the QtHelp engine section and have not found that information. Please let me know specifically where in the documentation this information is found.

[wysota]

Wysota, that's a cheap shot. You make it sound that any idiot should just know that assistant requires the sqldrivers with sqlite3. But I guess it's just a second nature to a brilliant guru like yourself.

You overestimate me It's all in the docs, really. Just not in a single place but if everything was in every possible place, the docs would take two DVDs and would be horrible to maintain and read.

huh?

I think the help collection file might contain all contents of help database, but as I said, I'm not sure of that. And you don't need both actually, the help collection file is only required for each separate set of help files.

What tutorial would that be?

"Generating Qt Help" in QtHelp module. Just before this tutorial it is said:

Instead, only the compressed help file and optionally the collection file has to be distributed.

Didn't you mean exactly that?

The next paragraph says:

So, in general, there are four files interacting with the help system, two used for generating Qt help and two meant for distribution:

... and then there is the tutorial.

As for the part about help being stored in a database - it is somewhere there although I agree it would be nice if it was pointed out specifically. You might want to post a suggestion to qt-bugs about it.

[jml]

Point taken regarding the paragraph

As already mentioned, the Qt compressed help file contains all data, so there is no need any longer to ship all single html files. Instead, only the compressed help file and optionally the collection file has to be distributed. The collection file is optional since any existing collection file, e.g. from an older release could be used.

It's a bit cryptic and buried, but I should have seen that. Still doesn't address the sqldrivers part.

It's probably pointless to continue a discussion of the quality of the documentation in this case, since neither of us actually wrote it. However I don't think it is too much to ask that regard to assistant as a help viewer, that either the QtHelp engine section, or the Qt deployment section contain some explicit section as to what is required in deploying the assistant help viewer. This would not require 2 DVDs.

Anyway, we've probably said enough on this thread.

[wysota]

This would not require 2 DVDs.

No, it wouldn't. But there are hundreds such places througout the documentation. There are other online resources you may use, remember that. For instance once you get experienced with deploying assistant as a help browser, you might write an article about it in our wiki.