Building a static Qt for Windows using MinGW: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
No edit summary
(mention how to get a static build in the warning header)
 
(18 intermediate revisions by 10 users not shown)
Line 1: Line 1:
[toc align_right="yes" depth="3"]
{{LangSwitch}}


= How to build a static Qt for Windows/MinGW =
=='''WARNING'''==
The information on this page is '''outdated'''!


== Dynamic and static versions of Qt ==
Please refer to the official documentation for instructions how to build Qt on Windows: https://doc.qt.io/qt-6/windows-building.html


=== Why a static Qt? ===
Also, the rationale why to use a static build is questionable. See https://doc.qt.io/qt-6/windows-deployment.html for how to deploy a Qt application on Windows.


On Windows, the pre-built environments from "qt.io":http://qt.io/download are dynamically linked. This means that your Qt application dynamically references the Qt DLL's which are installed with the pre-built environment.
If you still want a static build, add <code>-static</code> to the <code>configure</code> arguments.


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":http://www.dependencywalker.com/ 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.
===Why a static Qt?===
 
On Windows, the pre-built environments from [http://qt.io/download 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 [http://www.dependencywalker.com/ 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.
This article describes an automated way of downloading, building and installing a static Qt development environment using a Windows PowerShell script.
Line 15: Line 20:
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.
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 ===
===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.
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.
Line 21: Line 26:
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.
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 ===
===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:
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: from a pre-built package.<br />''' A static version, installed in '''C: using the procedure which is described in this article.
*A dynamic version, installed in '''C:\Qt''' from a pre-built package.
<br />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.
 
<br />The static environment shall 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 contains only 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.
*A static version, installed in '''C:\Qt\Static''' using the procedure which is described in this article.
<br />h3. Restrictions in a static environment
 
<br />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.
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.
<br /># There are licensing issues in distributing applications embedding Qt code in a static link. See "here":http://qt.io/products/licensing and "here":https://blog.qt.io/blog/2009/11/30/qt-making-the-right-licensing-decision/ 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.<br /># 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.
 
<br />Also note the following points:
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.
<br />''' 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.
===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.
 
#There are licensing issues in distributing applications embedding Qt code in a static link. See [http://qt.io/products/licensing here] and [https://blog.qt.io/blog/2009/11/30/qt-making-the-right-licensing-decision/ 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.
#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.


== Prerequisites ==
#Obtain the Qt Installer from [http://qt.io/download qt.io] and install the relevant pre-build Qt environment. For example, "Qt 5.15.2 MinGw 8.1.0 32-bit"
#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.
#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).


=== Dynamic pre-built Qt environment ===
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).


Install the dynamic pre-built package from "qt.io":http://qt.io/download. Select the package named "Qt for Windows 32-bit (MinGW, OpenGL)". The exact name and version may vary. You can also "browse the tree of installation packages":http://download.qt.io/official_releases/qt/.
[https://imgbox.com/Gh3uAWIx Example image] of the Qt Installer with what was selected to write this guide.


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. At the time of writing of this article, the latest Qt version is "'''5.2.0'''":http://download.qt.io/official_releases/qt/5.2/5.2.0/qt-windows-opensource-5.2.0-mingw48_opengl-x86-offline.exe.
===Windows PowerShell===


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).
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.
<br />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).


=== Windows PowerShell ===
===7-Zip===


The script which builds the static Qt environment is a PowerShell script.
The build script also requires [http://www.7-zip.org/ 7-Zip] to uncompress the downloaded Qt source code. Be sure to install it first.


The PowerShell version 3.0 or higher is required. PowerShell 3.0 comes with Windows 8 but it can be installed on Windows 7 as well from "Microsoft download":http://www.microsoft.com/en-us/download/details.aspx?id=34595. It is probably impossible to install PowerShell 3.0 on Windows XP or Vista. This article consequently applies to Windows 7 and higher only.
===Qt build dependancies===


=== 7-Zip ===
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):


The build script also requires "7-Zip":http://www.7-zip.org/ to uncompress the downloaded Qt source code. Be sure to install it first.
*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 ==
==Building the Qt static environment==


=== Download and run, all done ===
===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.'''


Download the script named "windows-build-qt-static.ps1":https://sourceforge.net/p/qtlmovie/code/ci/master/tree/build/windows-build-qt-static.ps1?format=raw and execute it.
1. Take a copy of the following PowerShell script on github: [https://gist.github.com/mrfaptastic/80e909c9a8237994471bce2d17657779 qt-windows-static-build.ps1]


The above link fetches the script directly from the git repository of a small open-source project named "QtlMovie":http://sourceforge.net/projects/qtlmovie/. You may want to have a look at the various build scripts in this project for sample application builds and installations.
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:<syntaxhighlight lang="powershell">
[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 '''windows-build-qt-static.ps1''' script can be directly invoked from the Windows Explorer if you are ok with the default parameter values (see below). If you are not familiar with PowerShell, simply right-click on the file and select "Run with PowerShell".
</syntaxhighlight>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.<syntaxhighlight lang="powershell">
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"


The script performs the following steps:
</syntaxhighlight>3. Execute the script '''in Windows PowerShell''' as a non-administrator user:<syntaxhighlight lang="powershell">
.\qt-windows-static-build.ps1
</syntaxhighlight>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:


# Download Qt source code.
#Download the Qt everything source code.
# 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.)
#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.)
# Install the static version of Qt in C:by default.
#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.
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 ===
===Command line syntax===


Alternatively, you can invoke the script from the PowerShell prompt using the following syntax:
Alternatively, you can invoke the script from the PowerShell prompt using the following syntax:
Line 80: Line 116:
'''windows-build-qt-static.ps1 [-QtSrcUrl ''url''] [-QtStaticDir ''directory''] [-QtVersion ''string''] [-MingwDir ''directory''] [-NoPause]'''
'''windows-build-qt-static.ps1 [-QtSrcUrl ''url''] [-QtStaticDir ''directory''] [-QtVersion ''string''] [-MingwDir ''directory''] [-NoPause]'''


=== Command line parameters ===
===Command line parameters===
 
'''-QtSrcUrl ''url'''''
'''-QtSrcUrl ''url'''''


Specify the URL of the Qt source file archive. By default, the latest identified version is hardcoded ("Qt 5.2.0":http://download.qt.io/official_releases/qt/5.2/5.2.0/single/qt-everywhere-opensource-src-5.2.0.7z at the time of this article was written).
Specify the URL of the Qt source file archive.  


Instead of using the parameter on the command line, you may want to modify the default value in the script using another URL / version. Update the following line:
'''-QtStaticDir ''directory'''''
 
<code><br /> $QtSrcUrl = "http://download.qt.io/official_releases/qt/5.2/5.2.0/single/qt-everywhere-opensource-src-5.2.0.7z",<br /></code>


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


Specify the root directory where the static versions of Qt are installed. By default: '''C:.
'''-QtVersion ''string'''''
<br />'''-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.2.0" 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.
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'''''
'''-MingwDir ''directory'''''
Line 101: Line 133:
Specify the root directory of the MinGW environment. By default, use the version which was installed by the prebuilt Qt environment.
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.2.0 is installed for instance, the script locates MinGW in '''C:5.2.0\Tools\mingw48_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.
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'''
'''-NoPause'''
Line 107: Line 139:
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.
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==


=== Command line ===
===Using the Qt static environment with Qt Creator (recommended)===


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.
This section describes how to use the static Qt environment from Qt Creator.  


Simply add the ''bin'' subdirectory of the static Qt environment in front of the ''Path'' environment variable. For Qt 5.2.0, this is '''C:.2.0\bin'''.
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.


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 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.


The following commands summarize the command line setups for the various environments.
====Qt Creator Configuration====


Dynamic pre-built Qt with the traditional Windows command shell:<br /><code><br />set Path=C:5.2.0\5.2.0\mingw48_32\bin;C:5.2.0\Tools\mingw48_32\bin;C:5.2.0\Tools\QtCreator\bin;C:32;C:</code>
#Open the Qt Creator
#Tools (menu) -> Option
#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.
#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"
#Then go to tab "Kits". Again, there must be an "Auto-detected" part and an initially empty "Manual" part.
#Click "Add".
#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.


Dynamic pre-built Qt with the Windows PowerShell:<br /><code><br />$env:Path=C:5.2.0\5.2.0\mingw48_32\bin;C:5.2.0\Tools\mingw48_32\bin;C:5.2.0\Tools\QtCreator\bin;C:32;C:</code>
Then click "OK" to terminate the options setup.


Static Qt build with the traditional Windows command shell:<br /><code><br />set Path=C:.2.0\bin;C:5.2.0\Tools\mingw48_32\bin;C:32;C:</code>
====Your Project Configuration====


Static Qt build with the Windows PowerShell:<br /><code><br />$env:Path=C:.2.0\bin;C:5.2.0\Tools\mingw48_32\bin;C:32;C:</code>
#In each project you want to deploy with a static build, edit the project setup (select "Projects" in the left vertical pane).
#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.
#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.
#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.


=== Using the Qt static environment with Qt Creator ===
===Command line===


This section describes how to use the static Qt environment from Qt Creator. Note that Qt Creator itself is part of the dynamic pre-built environment. By default, it builds the applications for this dynamic environment. But it is possible to configure it to additionally use the static Qt environment.
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.


The following description is based on a vanilla Qt 5.2.0 / Qt Creator 3.0.0 installation, without additional customization of Qt Creator. Change the version numbers to adapt to your configuration.
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'''.


==== Qt Creator setup ====
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.


Open the Qt Creator options edit box (menu "Tools" then "Options…"). Select "Build &amp; Run".
The following commands summarize the command line setups for the various environments.


Go to tab "Qt Versions". 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.2.0 MinGW 32bit C:5.2.0\5.2.0\mingw48_32\bin\qmake.exe". The "Manual" part is initially empty.
Dynamic pre-built Qt with the traditional Windows command shell:


Click "Add", browse to C:.2.0\bin and select "qmake.exe". The version name is automatically set to "Qt 5.2.0 (5.2.0)". You should set a more meaningful name such as "Qt 5.2.0 MinGW Static 32bit"
<code>
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;</code>


Then go to tab "Kits". Again, there must be an "Auto-detected" part and an initially empty "Manual" part. Click "Add". Set a meaningful name such as "Desktop Qt 5.2.0 MinGW Static 32bit". In the "Qt version" field, select your static environment, named "Qt 5.2.0 MinGW Static 32bit" if you followed the above advice.
Dynamic pre-built Qt with the Windows PowerShell:
 
Then click "OK" to terminate the options setup.


==== Project setup ====
<code>
$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;</code>


In each project you want to deploy with a static build, edit the project setup (select "Projects" in the left vertical pane).
Static Qt build with the traditional Windows command shell:


Click "Add Kit" in the upper left corner and select your static kit, named "Desktop Qt 5.2.0 MinGW Static 32bit" if you followed the above advice.
<code>
set Path=C:\Qt\Static\5.15.2\bin;C:\Qt\5.15.2\mingw81_32\bin;C:\Qt\Tools\mingw810_32\bin;</code>


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.
Static Qt build with the Windows PowerShell:


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.
<code>
$env:Path=C:\Qt\Static\5.15.2\bin;C:\Qt\5.15.2\mingw81_32\bin;C:\Qt\Tools\mingw810_32\bin;</code>


Note that it is recommended to build only release versions of the application with the static environment. Avoid building a debug version of the application with the static environment. There are several reasons for that:
===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 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:
*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 + Release: 1 MB
** Dynamic + Debug: 33 MB
**Dynamic + Debug: 33 MB
** Static + Release: 16 MB
**Static + Release: 16 MB
** Static + Debug: 297 MB
**Static + Debug: 297 MB


[[Category:HowTo]][[Category:Windows]][[Category:MinGW]]
[[Category:HowTo]]
[[Category:Windows]]
[[Category:MinGW]]

Latest revision as of 09:42, 9 September 2022

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

WARNING

The information on this page is outdated!

Please refer to the official documentation for instructions how to build Qt on Windows: https://doc.qt.io/qt-6/windows-building.html

Also, the rationale why to use a static build is questionable. See https://doc.qt.io/qt-6/windows-deployment.html for how to deploy a Qt application on Windows.

If you still want a static build, add

-static

to the

configure

arguments.

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 MinGw 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):

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