Trolltech | Documentation | Qt Quarterly | Implementing Model/View/Controller »

Deploying Applications on Windows
by Andy Shaw

Update: The information in this article applies to Qt 3. See the Qt Reference Documentation for the latest information.

This article is the second in a series of three covering the deployment of Qt applications on various platforms. Here the focus is on Windows. Just like Mac OS X applications, deploying an application on Windows does not require any C++ programming. All you need to do is build Qt and your application in release mode, and follow the procedures described in this article. We will demonstrate the procedures in terms of deploying the showimg application that is provided in Qt's examples directory.

Static Linking

If you want to keep things simple by only having a single file to deploy, i.e. a stand-alone executable, then you must build everything statically. As with static linking on Mac OS X, the advantages are that the application will load and execute faster because all the symbols are in the executable. The disadvantages are the increase in size of the executable, and the fact that you cannot use plugins with statically linked applications.

Before we can build our application we must make sure that Qt is built statically. To do this go to a command prompt and type the following:

    cd %QTDIR%
    configure -static <any other options you need>
    

Remember to specify any other options you need, such as thread support, as arguments to configure. Once configure has finished, type the following:

    make sub-src
    

This will build Qt statically in release mode. [1] Once Qt has finished building we can build the showimg application.

First we must go into the directory that contains the application we want to deploy:

    cd examples\showimg
    

We must now run qmake to create a new makefile for the application, and do a clean build to create the statically linked executable:

    qmake showimg.pro
    make clean
    make
    

Now, provided that everything compiled and linked without any errors we should have a showimg.exe file that is ready for deployment. One easy way to check that the application really can be run stand-alone is to copy it to a machine that doesn't have Qt or any Qt applications installed, and run it on that machine.

Shared Libraries

If you don't want to use static linking, for example, because you want to use plugins, or because you want to use the same Qt DLL for a family of applications, then the solution is to use a shared library.

As with static linking, before we can build our application we must make sure that Qt is built as a shared library. To do this go to a command prompt and type the following:

    cd %QTDIR%
    configure -shared <any other options you need>
    

Remember to specify any other options you need, such as thread support, as arguments to configure. Since we are still using the showimg application as an example we will also specify -plugin-imgfmt-jpeg as an option, so that there will be at least one plugin. Once configure has finished, type the following:

    make sub-plugins
    

This will build Qt as a shared library in release mode, and build the JPEG image format plugin. Once Qt has finished building we can build the showimg application. First we must go into the directory that contains the application we want to deploy:

    cd ..\examples\showimg
    

Now run qmake to create a new makefile for the application, and do a clean build to create the dynamically linked executable:

    qmake showimg.pro
    make clean
    make
    

If everything compiled and linked without any errors, we will get a showimg.exe file. To deploy it, we must make sure that we copy the Qt DLL as well as the executable to a suitable directory. (We'll cover the JPEG image format plugin shortly.) First we'll check that the application will work in a deployed environment. Either copy the executable and the Qt DLL to a machine that doesn't have Qt or any Qt applications installed, or if you want to test on the build machine, unset the QTDIR environment variable and remove %QTDIR%\bin from the PATH environment variable.

We should now have the showimg.exe executable and the Qt DLL (e.g., qt331.dll, or if you have configured with threading support, qt-mt331.dll), in a directory together. At a command prompt, change to this directory and try running the program.

If the application starts up without any problems, then we have successfully made a dynamically linked version of the showimg application. If you try opening a PNG image using the application, the image should be displayed correctly; but if you try opening a JPEG image, nothing will happen since we have not yet deployed the JPEG plugin with the application.

Plugins

Plugins work differently to normal DLLs, so we can't just copy them into the same directory as our application's executable as we did with the Qt DLL. Qt applications look for plugins in a subdirectory within the their own directory, for instance, an image format plugin should be in the application's imageformats subdirectory, and a SQL driver plugin should be in the application's sqldrivers subdirectory.

So to make the JPEG plugin available to our showimg application, we just have to change directory to the application's directory and copy over the appropriate DLL:

    mkdir imageformats
    copy %QTDIR%\plugins\imageformats\qjpeg100.dll imageformats
    

(If you unset the QTDIR environment variable, you will have to type the absolute path to your Qt directory rather than use %QTDIR%.) If you run the showimg application and open a JPEG image, the image will now load correctly.

One benefit of using plugins is that they can easily be made available to a whole family of applications. For example, if we have several applications that need JPEG support, it might be more convenient to use a common plugin directory for all our plugins. Also, we might decide to put all our plugins in the "C:\QtPlugins" directory. If we use a custom directory, we must still use subdirectories for the different types of plugin, so our image format plugins would go in "C:\QtPlugins\imageformats". To make our applications aware of this additional plugins directory, we must add the following line, before the application needs to load the plugins:

    qApp->addLibraryPath("C:\\QtPlugins");
    

It's often most convenient to add the path in the application's main() function, right after the QApplication object is created. Once the path is added, the application will search it for plugins, in addition to looking in subdirectories in the application's own directory. Any number of additional paths can be added.

C Runtime Wrinkle

Sometimes you will need to distribute the C runtime library with your application. Most Windows versions will already have the runtime library installed, but if you are using a modern Visual Studio, this may not be the case. You can check which libraries your application is linking against by using the depends tool. To use the depends tool, all you need to do is to run it like this:

    depends <application executable>
    

This will provide a list of the libraries that your application depends on and other information. If you look in the top-left section, you can see the list of libraries. The ones that you will want to check for start with "MSVC"; to be certain that you have the right libraries available, make sure you copy those libraries along with your application executable.

Conclusion

This article has covered the key deployment issues for Qt applications on Windows. We haven't mentioned specific versions of Windows, since there's no need to; Qt applications built on one version of Windows will work on another without changes.


[1] Note that we have used make in all the examples, but if you use Microsoft Visual C++, you must use nmake instead.


This document is licensed under the Creative Commons Attribution-Share Alike 2.5 license.

Copyright © 2004 Trolltech Trademarks Implementing Model/View/Controller »