Building a static Qt for Windows using MinGW

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

Why a static Qt?

On Windows, the pre-built environments from qt.io are dynamically linked. This means that your Qt application dynamically references the Qt DLL's which are installed with the pre-built environment.

This is probably the preferred environment for developing and debugging since everything is there and ready to use. However, when it comes to deploying an application on systems without pre-installed Qt environments, it becomes complicated. There are several DLL’s to deploy with the application. Even using the classical DLL Dependency Walker tool, you cannot find all required DLL’s since some of them are dynamically loaded at execution. So, when the application is ready to deploy, it is easier to build a static version of it. But building a static version of the application requires a static version of the Qt environment in addition to the pre-built dynamic Qt environment.

This article describes an automated way of downloading, building and installing a static Qt development environment using a Windows PowerShell script.

Note that building and installing a static version of Qt on Windows was somewhat problematic up to Qt 4. But Qt 5 has now a much better support for static builds on Windows and this article takes advantage of that.

MinGW vs. MSVC

On Windows, two pre-built environments can be downloaded: one using MinGW and one using Microsoft Visual Studio. The two environments are incompatible and cannot be mixed. You have to choose one.

This article describes how to build a static version of Qt in a MinGW environment. If you need a static Qt for MSVC, you may probably find some ideas here but there is definitely some extra work.

Target environment

When you develop Qt applications on Windows and need to deploy them later on "general purpose" Windows machines, the recommended Qt environment contains two distinct builds of the same version of Qt:

• A dynamic version, installed in C:\Qt from a pre-built package.

• A static version, installed in C:\Qt\Static using the procedure which is described in this article.

The pre-built dynamic environment shall be used for development and debugging. In addition to the Qt command line tools (qmake, moc, uic, lupdate, lrelease, etc.), it contains the high-level GUI tools such as Qt Creator, Assistant, Linguist, etc. The installation is straightforward, everything is here, well integrated, working like a charm.

The static environment should only be used to release the deployment version of the application, after it has been fully developed and debugged using the dynamic environment. The static environment should only be compiled to contain the Qt command line tools. There are at least two reasons for not building static versions of the GUI tools. First, releasing a new version of an application is typically a task that you automate using a script and there is no need for GUI tools at this stage. Second, it is probably impossible to build a static version of Qt Creator because of the lack of support for plugins in a static environment.

Restrictions in a static environment

Although building a static version of your application makes it easier to deploy, there are some restrictions in a static environment. Be sure to check that your application complies with these constraints before going further.

1. There are licensing issues in distributing applications embedding Qt code in a static link. See here and here for more details. While you are probably safe if your application is distributed according to the terms of a recognized free and open-source license, you should definitely check the licensing issue for proprietary or closed-source applications.
2. The application cannot use a dynamic modular approach using plugins. But you cannot both ask for a static environment and for a dynamic loading of your own DLL's.

Also note the following points:

• The static executable file of the application is bigger than the dynamic one since all used Qt code is copied into the executable. However, if your application has only one executable, the total deployed size is smaller since only the Qt code which is actually used is linked. When deploying a dynamic version of the application, you have to install all required Qt DLL's with the application and the overall size of all these DLL's is larger than the static application.
• A Qt static build means that no Qt or MinGW DLL's are used. However, the static executable file of the application still references the Windows DLL's such as kernel32.dll or user32.dll. These DLL's, however, are installed with Windows and do not need to be deployed with the application.

Prerequisites

Dynamic pre-built Qt environment

You must have a pre-built Qt environment installed before you attempt to build a static version of the library with the Qt source code.

1. Obtain the Qt Installer from qt.io and install the relevant pre-build Qt environment. For example, "Qt 5.15.2 MiniGw 8.1.0 32-bit"
2. Preferably plan the installation of the same version of Qt for the dynamic and static builds. This is not a strict requirement but it is a safe configuration.
3. During installation, select the default installation location (C:\). Be sure to add the MinGW environment in the installation (selectable in the "Tools" branch of the installation options).

If you have a separated MinGW environment that you prefer to use and do not install the one from the Qt package installer, be sure to specify the option -MingwDir in the static build script (see below).

Example image of the Qt Installer with what was selected to write this guide.

Windows PowerShell

The script which builds the static Qt environment is a PowerShell script. PowerShell version 3.0 or higher is required. It is recommended to use Windows 10 which comes with PowerShell version 5 and onwards.

7-Zip

The build script also requires 7-Zip to uncompress the downloaded Qt source code. Be sure to install it first.

Qt build dependancies

As per the README that is packaged with the qt-everywhere-* zip package, it is noted that for windows the following also need to be available (as at Qt version 5.15.2):

• Perl version 5.12 or later (http://www.activestate.com/activeperl/)
• Python version 2.7 or later (http://www.activestate.com/activepython/)
• Ruby version 1.9.3 or later (http://rubyinstaller.org/)

Building the Qt static environment

Using the Windows Powershell script

The PowerShell script aims to assist with the install of the qt source code and the compilation of Qt as a static binary. For the purposes of the below instructions, Qt version 5.15.2 is used with Windows 10.

1. Take a copy of the following PowerShell script on github: qt-windows-static-build.ps1

2. Edit the script as required to change the variables which define the Qt version and directory location of the Qt pre-built environment already installed. Specifically the lines:

[CmdletBinding()]
param(
    $QtSrcUrl = "https://download.qt.io/official_releases/qt/5.15/5.15.2/single/qt-everywhere-src-5.15.2.zip",
    $QtStaticDir = "C:\Qt\Static", # NO TRAILING SLASH
    $QtVersion = "5.15.2", #If you change this, you'll need to change the URL above to download as well...
    $MingwDir = "",
    [switch]$NoPause = $false
)

The script contains flags to 'configure' what to include in the Qt static build. By default it removes a lot of modules that probably are not required for most applications. However, if your requirements differ - modify this line of the script accordingly.

cmd /c "configure.bat -static -release -platform win32-g++ -opensource -confirm-license -prefix $QtDir -qt-zlib -qt-libpng -qt-webp -qt-libjpeg -qt-freetype  -no-opengl -skip qt3d -skip qtactiveqt -skip qtandroidextras -skip qtcharts -skip qtconnectivity -skip qtdatavis3d -skip qtdeclarative -skip qtdoc -skip qtgamepad -skip qtlocation -skip qtlottie -skip qtmacextras -skip qtmultimedia -skip qtnetworkauth -skip qtpurchasing -skip qtquick3d -skip qtquickcontrols -skip qtquickcontrols2 -skip qtquicktimeline -skip qtremoteobjects -skip qtscript -skip qtsensors -skip qtspeech -skip qtsvg -skip qtwayland -skip qtwebglplugin -skip qtwebview -skip webengine -make libs -nomake tools -nomake examples -nomake tests"

3. Execute the script in Windows PowerShell as a non-administrator user:

.\qt-windows-static-build.ps1

The PowerShell script will check to see if your path variable is configured correctly such that 'powershell', 'ruby', 'python' and 'perl' commands are avaialble. If not, you will need to double check what you installed as covered in 'Qt build dependancies'. The PowerShell will now perform the following steps:

1. Download the Qt everything source code.
2. Build a static version of Qt using the MinGW compiler in the pre-built dynamic environment. It builds the libraries and the command line tools (qmake, moc, uic, lupdate, lrelease, etc.)
3. Install the static version of Qt in C:\Qt\Static by default.

The execution of this script may take a couple of hours to complete, depending on your processing power. So you have to be patient. Qt is a complex framework with a very large amount of code.

Command line syntax

Alternatively, you can invoke the script from the PowerShell prompt using the following syntax:

windows-build-qt-static.ps1 [-QtSrcUrl url] [-QtStaticDir directory] [-QtVersion string] [-MingwDir directory] [-NoPause]

Command line parameters

-QtSrcUrl url

Specify the URL of the Qt source file archive.

-QtStaticDir directory

Specify the root directory where the static versions of Qt are installed. By default: C:.

-QtVersion string

Specify the Qt version. By default, the script tries to extract the version number from the Qt source file name. Usually, this is sufficient, the script will find "5.15.2" or "5.0.0-rc1" for instance. If the naming scheme of the Qt source file changes one day, you may need to specify an explicit value to this parameter.

-MingwDir directory

Specify the root directory of the MinGW environment. By default, use the version which was installed by the prebuilt Qt environment.

When the prebuilt environment for Qt 5.15.2 is installed for instance, the script locates MinGW in C:\Qt\5.15.2\Tools\mingw492_32. If you chose not to install MinGW as part of the prebuilt environment for Qt, you have to specify the root directory of your MinGW installation.

-NoPause

Do not wait for the user to press enter at the end of execution. By default, the scripts executes a pause instruction at the end of execution, which is useful when the script was run from the Windows Explorer.

Using the Qt static environment

Using the Qt static environment with Qt Creator (recommended)

This section describes how to use the static Qt environment from Qt Creator.

Please note: Qt Creator is provided as part of the dynamic pre-built environment. By default, it builds the applications for this dynamic environment, but it is possible to configure projects to use the static Qt environment when required.

The following instructions are based on a standard Qt 5.15.2 / Qt Creator 4.14.2 installation. Change the version numbers to adapt to your configuration.

Qt Creator Configuration

1. Open the Qt Creator
2. Tools (menu) -> Option
3. Select 'Qt Versions' tab. In the "qmake location" table, there must be an "Auto-detected" part and a "Manual" part. In the "Auto-detected" part, there should be one line named "Qt 5.15.2 MinGW 32bit C:\Qt\Qt5.15.2\5.5\mingw492_32\bin\qmake.exe" (or whatever version of Qt you are working with). The "Manual" part is initially empty.
4. Click "Add", browse to C:\Qt\Static\<your static build version>\bin and select "qmake.exe". The version name is automatically set to "Qt 5.15.2 (5.15.2)". You should set a more meaningful name such as "Qt 5.15.2 MinGW Static 32bit"
5. Then go to tab "Kits". Again, there must be an "Auto-detected" part and an initially empty "Manual" part.
6. Click "Add".
7. Set a meaningful name such as "Desktop Qt 5.15.2 MinGW Static 32bit". In the "Qt version" field towards the bottom, select your static environment, named "Qt 5.15.2 MinGW Static 32bit" if you followed the above advice. Qt Creator should auto populate the Compiler details.

Then click "OK" to terminate the options setup.

Your Project Configuration

1. In each project you want to deploy with a static build, edit the project setup (select "Projects" in the left vertical pane).
2. Click "Add Kit" in the upper left corner and select your static kit, named "Desktop Qt 5.15.2 MinGW Static 32bit" if you followed the above advice.
3. The new kit for your project is configured. Note that, by default, there are distinct build directories for the dynamic and static versions of your project.
4. Now you can build your application in any combination of static vs. dynamic and release vs. debug. In the bottom part of the left pane, the project selector (the computer icon with the name of your project and either "Release" or "Debug") lets you select the combination you want.

Command line

This section describes how to use the static Qt environment from the command line, either the traditional Windows command shell (cmd.exe) or the Windows PowerShell.

Simply add the bin subdirectory of the static Qt environment in front of the Path environment variable. For Qt 5.15.2, this is C:\Qt\Static\5.15.2\bin.

Do not forget to also include the MinGW environment in the path. With the dynamic pre-built Qt environment, you may want to add Qt Creator also.

The following commands summarize the command line setups for the various environments.

Dynamic pre-built Qt with the traditional Windows command shell:

set Path=C:\Qt\5.15.2\mingw81_32\bin;C:\Qt\Tools\mingw810_32\bin;C:\Qt\Tools\QtCreator\bin;C:\Perl64\bin;C:\Ruby27-x64\bin;C:\ActivePython3;

Dynamic pre-built Qt with the Windows PowerShell:

$env:Path=C:\Qt\5.15.2\mingw81_32\bin;C:\Qt\Tools\mingw810_32\bin;C:\Qt\Tools\QtCreator\bin;C:\Perl64\bin;C:\Ruby27-x64\bin;C:\ActivePython3;

Static Qt build with the traditional Windows command shell:

set Path=C:\Qt\Static\5.15.2\bin;C:\Qt\5.15.2\mingw81_32\bin;C:\Qt\Tools\mingw810_32\bin;

Static Qt build with the Windows PowerShell:

$env:Path=C:\Qt\Static\5.15.2\bin;C:\Qt\5.15.2\mingw81_32\bin;C:\Qt\Tools\mingw810_32\bin;

When to use a Static Qt build

It is recommended to only build release versions of the application with at static Qt environment. Avoid building a debug version of the application with the static Qt environment. There are several reasons for this:

• The recommended environment for the development, debug and test phase is the pre-built dynamic environment, not the static one.
• The size of a static application in debug mode is insanely huge. For a given application, the following sizes have been observed for the application executable file:
  • Dynamic + Release: 1 MB
  • Dynamic + Debug: 33 MB
  • Static + Release: 16 MB
  • Static + Debug: 297 MB