Deploying Windows Applications

En Ar Bg De El Es Fa Fi Fr Hi Hu It Ja Kn Ko Ms Nl Pl Pt Ru Sq Th Tr Uk Zh

What does that mean?

In most cases the Qt applications you create don't reside on your development machine just to please you. You want to distribute them and make them run without any further hazzle and dependency installations on any Windows machine: Copy, Double-Click and Run.

Normally Qt applications are compiled and linked against shared libraries (Windows: DLL=Dynamic Link Library, Unix: .so=Shared Object). When the compiled program is executed the code from the libraries needed is loaded at runtime. The point is now to know which libraries have to be shipped along with your application to make it run without having a full Qt installation on the target system.

List of Libraries needed

Besides your compiled .exe file you need some libraries contained in the same directory as the executable. All needed libraries are located in your Qt installation bin directory, e.g. C:\Qt\5.4\mingw491_32\bin. If you have installed more than one development kits you need to copy the libraries from the correct kit of course.

WARNING: Don't take the library files from the QtCreator directory which is compiled against MSVC libraries and has different entry points.

In either case you need the following non-Qt libraries. The list was created from a Qt 5.4 installation:

Library Name	Size	Remarks
icudt53.dll	21M	Unicode Lib
icuin53.dll	3.6M	Unicode Lib
icuuc53.dll	2.0M	Unicode Lib
libgcc_s_dw2-1.dll	118K	GCC Lib
libstdc+–6.dll	1003K	Standard C+ Library
libwinpthread-1.dll	48K	Pthreads for Windows

Some might argue that there might arise a small problem with shipping 27M ICU libraries. If you don't need ICU (http://site.icu-project.org/) you have to recompile Qt with ./configure -without-icu.

Next we need — depending on what your application needs — to copy the Qt DLLs. First have a look at your .pro file that has a line like:

QT += widgets

In this case you need to copy the following files:

Library Name	Size	Remarks
Qt5Core.dll	4.7M	Qt Core classes — always needed!
Qt5Gui.dll	5.0M	Graphical User Interface Classes
Qt5Widgets.dll	6.2M	Widget Classes

So far for the core libraries to make the program run on other machines. But wait. Something important is missing:

Platform Plugins

Some vital functions for starting Windows applications are contained in qwindows.dll Located in C:\Qt\5.4\mingw491_32\plugins\platforms. Copying this file to the same directory to the other DLLs would not work. This file is expected in the platforms subdirectory:

.
├── Qt5Core.dll
├── Qt5Gui.dll
├── Qt5Sql.dll
├── Qt5Widgets.dll
├── icudt53.dll
├── icuin53.dll
├── icuuc53.dll
├── libgcc_s_dw2-1.dll
├── libstdc–6.dll
├── libwinpthread-1.dll
└── platforms
    └── qwindows.dll

Now your application is good to go and able to run on other machines not having a full blown Qt installation preinstalled. Unfortunately you still need to ship a total of approximately 45M (half without ICU).

Database Applications

When shipping applications that need to establish a database connection you need to ship the Qt5Sql.dll and the database driver library you use to connect to the database. In this example we make use of SQLite:

.
├── Qt5Core.dll
├── Qt5Gui.dll
├── Qt5Widgets.dll
├── Qt5Sql.dll
├── icudt53.dll
├── icuin53.dll
├── icuuc53.dll
├── libgcc_s_dw2-1.dll
├── libstdc+–6.dll
├── libwinpthread-1.dll
├── platforms
│   └── qwindows.dll
└── sqldrivers
    └── qsqlite.dll

You noticed that we created a sqldrivers directory holding the sqlite.dll copied from C:\Qt5.4\mingw491_32\plugins\sqldrivers

Building a Windows Installer

First head over to https://download.qt.io/official_releases/qt-installer-framework/ and download the package for your operating system.

After installation we need to create some files holding the installer meta data. I suggest creating a directory in your source root directory called installer with this structure:

.
├── config
│   └── config.xml
└── packages
    └── my-package
        ├── data
        │   ├── my-executable.exe
        │   ├── …
        │   .
        └── meta
            ├── installshortcut.qs
            ├── license.txt
            └── package.xml

The installer can be instructed to install one or more packages. They are all located in the packages subdirectory. In the above example we have one package called my-package. In the meta directory we store the license, an installation script for the Windows Shortcut and a package.xml containing the meta data:

package.xml contains:

<?xml version="1.0" encoding="UTF-8"?>
<Package>
  <DisplayName>Name of this Package</DisplayName>
  <Description>Short description</Description>
  <Version>1.0</Version>
  <ReleaseDate>2015-01-10</ReleaseDate>
  <Name>applicationname</Name>
  <Licenses>
  <License name="GPL" file="license.txt" />
  </Licenses>
  <ForcedInstallation>true</ForcedInstallation>
  <Script>installshortcut.qs</Script>
</Package>

The installshortcut.qs:

 function Component() {
 }

 Component.prototype.createOperations = function() {
  component.createOperations();

 if ( installer.value("os") === "win" ) {
  component.addOperation(
  "CreateShortcut",
  "@TargetDir@/my-executable.exe",
  "@StartMenuDir@/My Executable.lnk"
  );
  }
 }

And finally the main configuration file contained in config:

config.xml

<?xml version="1.0" encoding="UTF-8"?>
<Installer>
  <Name>My Executable</Name>
  <Version>1.0</Version>
  <Title>Description</Title>
  <Publisher>Simon Wilper</Publisher>
  <StartMenuDir>My Application</StartMenuDir>
  <TargetDir>@rootDir@my-application</TargetDir>
  <UninstallerName>Uninstall</UninstallerName>
</Installer>

Now to create the installer run the binarycreator:

c:\qtinstfw\bin\binarycreator.exe -v -offline-only -c config\config.xml -p packages setup.exe

This article is maintained by Simon Wilper