Deploy an Application on Windows: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
No edit summary
(Move some notes about windeployqt.exe to Appendix 3)
 
(8 intermediate revisions by 6 users not shown)
Line 1: Line 1:
h1. Deploy an Application on Windows
[[Category:HowTo]]
{{LangSwitch}}


This guide is written for Qt 5. It assumes that:
'''NOTE: The recommended way to deploy your application is to use the [https://doc.qt.io/Qt-5/windows-deployment.html official deployment tool (windeployqt)]. Try that first! Continue reading this guide only if ''windeployqt'' doesn't quite work for you.'''''
* The ''release version'' of your app works correctly when you build + run it from Qt Creator
* Your (dynamically-linked) copy of Qt is installed in C:.2.1\mingw48_32


== Overview ==
The ''windeployqt'' tool will gather files from a few different locations. Here is an example of an app that uses Qt Quick to display a picture (PACKAGE-SPECIFIC DLLS ARE NOT SHOWN):


To deploy a Qt app, you'll need to gather files from a few different locations. Here is an example of an app that uses Qt Quick to display a picture (NOTE: PACKAGE-SPECIFIC DLLS ARE NOT SHOWN):
[[File:Qt_Deployment_Structure_Windows.png]]


[[Image:http://i.imgur.com/S582DlV.png|Where to find files for deployment]]
Sometimes, your app might be missing some functionality after deployment. Perhaps a window is blank, an image doesn't show, or a music file won't play. If this happens, ''windeployqt'' has probably forgotten to include a file that is only loaded at runtime (like a plug-in DLL).


== Finding the Required Files ==
Here is a systematic (albeit brute-force) way to identify the missing files. This guide is written for Qt 5 and assumes that:
 
* The ''release version'' of your app works correctly when you build + run it from Qt Creator
See "Qt for Windows - Deployment":http://doc.qt.io/qt-5/windows-deployment.html for the official instructions.
* Your (dynamically-linked) copy of Qt is installed in C:\Qt\5.2.1\mingw48_32\
 
Sometimes though, the deployment might seem successful and your app launches, but some things don't work properly. Perhaps a window is blank, an image doesn't show, or a music file won't play. If this happens, you are probably missing a file that is only loaded at runtime (like a plug-in DLL).
 
These files can be tricky to identify. Here is a systematic way to deploy successfully.


=== Initial deployment (Quick and dirty) ===
=== Initial deployment (Quick and dirty) ===


# Close Qt Creator.
# Close Qt Creator.
# Copy the following into C:## The ''release version'' of '''MyApp.exe'''
# Copy the following into C:\Deployment\
## All the '''.dll files''' from C:.2.1\mingw48_32\bin## All the '''folders''' from C:.2.1\mingw48_32\plugins## (If you used QML) All the '''folders''' from C:.2.1\mingw48_32\qml# Rename C:to C: (This turns your PC into a clean environment, just like one that doesn't have Qt installed.)
## The ''release version'' of '''MyApp.exe'''
# Launch C:.exe.
## All the '''.dll files''' from C:\Qt\5.2.1\mingw48_32\bin\
## All the '''folders''' from C:\Qt\5.2.1\mingw48_32\plugins\
## (If you used QML) All the '''folders''' from C:\Qt\5.2.1\mingw48_32\qml\
# Rename C:\Qt\ to C:\QtHidden\ (This turns your PC into a clean environment, just like one that doesn't have Qt installed).
# Launch C:\Deployment\MyApp.exe.


If your app worked correctly, congratulations! You are almost ready for deployment. You don't want to ship a 1.5GB package though, so it's time to clean up unused files.
If your app worked correctly, congratulations! You are almost ready for deployment. You don't want to ship a 1.5GB package though, so it's time to clean up unused files.
Line 32: Line 31:
=== Final deployment (Cleaned up) ===
=== Final deployment (Cleaned up) ===


Do the deletion steps below in C:and all of its subdirectories. After each deletion, launch C:.exe and test it. If it stops working, restore the files you just deleted.
Do the deletion steps below in C:\Deployment\ and all of its subdirectories. After each deletion, launch C:\Deployment\MyApp.exe and test it. If it stops working, restore the files you just deleted.


# Launch MyApp.exe. While it is running, try to delete all DLLs. The DLLs that aren't used will go to the recycle bin, leaving behind only the DLLs that you need. (This trick doesn't work for .qml and qmldir files, however).
# Launch MyApp.exe. While it is running, try to delete all DLLs. The DLLs that aren't used will go to the recycle bin, leaving behind only the DLLs that you need. (This trick doesn't work for .qml and qmldir files, however).
Line 39: Line 38:


When you have removed all the files that you don't need,
When you have removed all the files that you don't need,
# Rename C:back to C:to restore your installation.
# Rename C:\QtHidden\ back to C:\Qt\ to restore your installation.
# Distribute your app.
# Distribute your app.


== Appendix: How to ask for help ==
== Appendix 1: How to ask for help ==


If you still get stuck,
If you still get stuck,
# Start a new post in the "Qt Project forum":http://forum.qt.io/viewforum/14/
# Start a new post in the [http://qt-project.org/forums/viewforum/14/ Qt Project forum]
# Say that you followed this guide. Say which attempts passed, and which attempts failed.
# Say that you followed this guide. Say which attempts passed, and which attempts failed.
# Describe how it fails, and provide any error messages that you see.
# Describe how it fails, and provide any error messages that you see.
# Provide a screenshot of the contents in C:
# Provide a screenshot of the contents in C:\Deployment\
 
Remember: The more info you provide, the better your chances of getting a solution!
 
== Appendix 2: Alternative tools ==
* [https://doc.qt.io/Qt-5/windows-deployment.html windeployqt] - The official deployment tool for Windows by the Qt Project
* [https://github.com/QuasarApp/CQtDeployer CQtDeployer] - A cross-platform deployment tool by QuasarApp
 
== Appendix 3: Some notes about windeployqt.exe ==
 
For example, if you have installed '''Qt lib 5.9.9''' in the default location, it would be installed in '''C:\Qt\5.9.9'''
 
* If you have chosen to install the MS VC 2013 x64 toolchain during the installation of Qt Creator, there will be a folder named '''msvc2013_64'''.
** The file '''windeployqt.exe''' would be located in '''C:\Qt\5.9.9\msvc2013_64\bin'''.
* If you have chosen to install the MS VC 2015 x86 toolchain during the installation of Qt Creator, there will be a folder named '''msvc2015'''.
** The file '''windeployqt.exe''' would be located in '''C:\Qt\5.9.9\msvc2015\bin'''.
* If you have chosen to install the MS VC 2015 x64 toolchain during the installation of Qt Creator, there will be a folder named '''msvc2015_64'''.
** The file '''windeployqt.exe''' would be located in '''C:\Qt\5.9.9\msvc2015_64\bin'''.
 
Do not move '''windeployqt.exe''' to another folder.
 
Create a folder and place your program (your EXE file) into it. Then, you will need to run '''windeployqt.exe'''.
 
For example, from the command line, run '''C:\Qt\5.9.9\msvc2013_64\bin\windeployqt.exe C:\MyFolder\MyProgram.exe'''
 
MyFolder is now ready. You can copy it to any other PC and run your '''MyProgram.exe'''.

Latest revision as of 09:29, 5 April 2023

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

NOTE: The recommended way to deploy your application is to use the official deployment tool (windeployqt). Try that first! Continue reading this guide only if windeployqt doesn't quite work for you.

The windeployqt tool will gather files from a few different locations. Here is an example of an app that uses Qt Quick to display a picture (PACKAGE-SPECIFIC DLLS ARE NOT SHOWN):

Qt Deployment Structure Windows.png

Sometimes, your app might be missing some functionality after deployment. Perhaps a window is blank, an image doesn't show, or a music file won't play. If this happens, windeployqt has probably forgotten to include a file that is only loaded at runtime (like a plug-in DLL).

Here is a systematic (albeit brute-force) way to identify the missing files. This guide is written for Qt 5 and assumes that:

  • The release version of your app works correctly when you build + run it from Qt Creator
  • Your (dynamically-linked) copy of Qt is installed in C:\Qt\5.2.1\mingw48_32\

Initial deployment (Quick and dirty)

  1. Close Qt Creator.
  2. Copy the following into C:\Deployment\
    1. The release version of MyApp.exe
    2. All the .dll files from C:\Qt\5.2.1\mingw48_32\bin\
    3. All the folders from C:\Qt\5.2.1\mingw48_32\plugins\
    4. (If you used QML) All the folders from C:\Qt\5.2.1\mingw48_32\qml\
  3. Rename C:\Qt\ to C:\QtHidden\ (This turns your PC into a clean environment, just like one that doesn't have Qt installed).
  4. Launch C:\Deployment\MyApp.exe.

If your app worked correctly, congratulations! You are almost ready for deployment. You don't want to ship a 1.5GB package though, so it's time to clean up unused files.

If it didn't work correctly, ask for help (see the Appendix)

Final deployment (Cleaned up)

Do the deletion steps below in C:\Deployment\ and all of its subdirectories. After each deletion, launch C:\Deployment\MyApp.exe and test it. If it stops working, restore the files you just deleted.

  1. Launch MyApp.exe. While it is running, try to delete all DLLs. The DLLs that aren't used will go to the recycle bin, leaving behind only the DLLs that you need. (This trick doesn't work for .qml and qmldir files, however).
  2. (If you used QML) Delete a few .qml files and try relaunching MyApp.exe. Repeat until you try all .qml files.
  3. (If you used QML) Delete qmldir files from the folders that have no more DLLs or .qml files

When you have removed all the files that you don't need,

  1. Rename C:\QtHidden\ back to C:\Qt\ to restore your installation.
  2. Distribute your app.

Appendix 1: How to ask for help

If you still get stuck,

  1. Start a new post in the Qt Project forum
  2. Say that you followed this guide. Say which attempts passed, and which attempts failed.
  3. Describe how it fails, and provide any error messages that you see.
  4. Provide a screenshot of the contents in C:\Deployment\

Remember: The more info you provide, the better your chances of getting a solution!

Appendix 2: Alternative tools

  • windeployqt - The official deployment tool for Windows by the Qt Project
  • CQtDeployer - A cross-platform deployment tool by QuasarApp

Appendix 3: Some notes about windeployqt.exe

For example, if you have installed Qt lib 5.9.9 in the default location, it would be installed in C:\Qt\5.9.9

  • If you have chosen to install the MS VC 2013 x64 toolchain during the installation of Qt Creator, there will be a folder named msvc2013_64.
    • The file windeployqt.exe would be located in C:\Qt\5.9.9\msvc2013_64\bin.
  • If you have chosen to install the MS VC 2015 x86 toolchain during the installation of Qt Creator, there will be a folder named msvc2015.
    • The file windeployqt.exe would be located in C:\Qt\5.9.9\msvc2015\bin.
  • If you have chosen to install the MS VC 2015 x64 toolchain during the installation of Qt Creator, there will be a folder named msvc2015_64.
    • The file windeployqt.exe would be located in C:\Qt\5.9.9\msvc2015_64\bin.

Do not move windeployqt.exe to another folder.

Create a folder and place your program (your EXE file) into it. Then, you will need to run windeployqt.exe.

For example, from the command line, run C:\Qt\5.9.9\msvc2013_64\bin\windeployqt.exe C:\MyFolder\MyProgram.exe

MyFolder is now ready. You can copy it to any other PC and run your MyProgram.exe.