How to statically link Qt 4
Make your entire Qt application work entirely from a single file.
I was downloading Ubuntu Netbook Remix for my EeePC 900A and found that it’s installer is not a CD image, but a raw image meant to be written to a USB FLASH drive. After downloading their handy image writer, I found that this simple utility came with quite a few support files, including a surprising 13.5MB of .dlls.
This image writer tool was written using Nokia’s Qt software, which allows easy development and distribution for all the major platforms from a single C++ source base. This program was compiled in the same way most Windows software is today — with “dynamic linking”, requiring the Qt libraries, among others, be shipped with the program as separate files.
This is fine for large software projects, but it’s a little cumbersome for small tools like this one. Many programs can be distributed such that all necessary files are built into the executable in a process called static linking. Sometimes it is nice to be able to download just the program itself and not have to worry about making sure various DLLs are included (though setting up an installer largely eliminates this problem).
Static linking has its advantages and disadvantages, but when not done, running a program unaccompanied by even one support file will result in a cryptic error for the user:
These 4 steps are all you need to make your entire project result in a single, easy-to-distribute .EXE file:
- Complete your Qt project using normal debug libraries.
- Compile the Qt libraries for static linking (needs to be done only once).
- Add the necessary lines of code to include any Qt plugins you may need.
- Compile your release version with the static libraries.
Step 1: Complete your Qt project as usual using normal debug libraries. Do not use a static-compiled Qt build for development!
I’ll leave this to you. If you aren’t sure how to proceed, start here.
Step 2: Compile the Qt libraries for static linking
While not difficult, this is beyond the scope of the article. Building static Qt is fairly easy, and is covered in this article. It also covers how to shrink Qt (13.5MB is large even without static linking), and how to build Qt with several popular compilers..
Step 3: Add the necessary lines of code to include any Qt plugins you may need.
First, enable the Qt plugins needed by your project.
Only a small number of Qt features are part of a plugin (the rest will work simply by including the appropriate header). There are several commonly used plugins.
Image formats:
Database support:
Asian language codecs:
And finally, qtaccessiblewidgets for support of assistive technologies.
I’ll use the Oracle plugin (qsqloci) and the GIF image plugin (qgif) in the example below. Regardless of the plugins you need, they will be used in exactly the same manner.
Edit your project (.pro) file. It should be in the same folder as your source code. It should look something like this:
TARGET = YourProjectName TEMPLATE = app SOURCES += main.cpp window.cpp HEADERS += window.h
Add the following lines:
CONFIG += static static { // Everything below takes effect with CONFIG += static
CONFIG += static QTPLUGIN += qsqloci qgif
DEFINES += STATIC // Equivalent to "#define STATIC" in source code
message("Static build.")
}
Finally, edit your main.cpp and add the following to the top:
#include <QtPlugin>
Q_IMPORT_PLUGIN(qsqloci) Q_IMPORT_PLUGIN(qgif)
(in both files, replace qsqloci and qgif with your plugins)
Step 4: Compile your release version with the static libraries.
No extra effort is required to compile your application with static libraries. Configure your project to compile in “release” mode (not debug mode) and then ensure the environment is aware of the location.
In Microsoft Visual Studio 2008 Professional:
- Download and install the Visual Studio add-on.
- Start MSVC++ and open the Qt Options menu:
- Name the Qt installation as you like, then add the path.
In Qt. Creator the process is similar:
- Click Tools –> Options, and in “Qt Versions” shown below, click the plus sign icon and add your Qt installation as before:
Qt Creator note: If you are using Qt Creator for your projects and have compile errors, deselect “use jom instead of nmake” under Tools –> Options –> Projects.
That’s it.
Compile your application normally and notice the (surprisingly large) executable file in the release folder.
To actually make the Qt libraries usable in static linking, and to make them much smaller than their default distribution, see this article.
Very nice write-up Charles.
Windows Folks who may be scratching their heads in reaction to ‘Qt’ may not be aware that Qt reigns supreme in the Linux world as one of the best Framework development platforms, so much so, Nokia acquired the company (then named TrollTech).
http://en.wikipedia.org/wiki/Qt_%28toolkit%29
Some notable applications developed with this toolset:
o Skype
o KDE Desktop
o Google Earth
o SUN VirtualBox
While the Qt toolset is not GPL, it’s license has gone through several iterations to satisfy the FOSS community, and continue its use in KDE development.
I left the KDE fold and went to GNOME Desktop when KDE 4.0 arrived because it was a ‘hurting puppy’ in its initial revision.
KDE has suffered ‘growing pains’ during the last year, but has prevailed to become a fairly stable desktop (when compared to KDE 3.5.x) in its current revision, 4.3.1.
Anyhow, yes, Qt is NOT a ‘johnny come lately’ product Folks.
Get under the hood and check it out!
Detrich, you may like to read an informative but poorly titled post about making KDE 4 have a “less innovative” interface than its defaults: http://linux-blog.org/hate-kde4-ignorance-is-probably-the-culprit
I prefer Gnome to KDE 4 now too, but I still think that the Qt framework it’s built with is an important software development tool. It’s like a well-designed, multi-platform MFC.
Good post. Still waiting for the howto on compiling the Qt libraries for static linking
@Frode
I’ll try to finish that up this weekend or otherwise ASAP.
@Frode
Published.
Best articles from Charles on internet about QT & Static
I have question. How to statically link QtSolutions? When I use QtSolution plugin and I compile static project, application requests for all Qt libs. How can I solve this problem?
Hi,
I am a complete newbie to QT Creator (1.3) and QT. I am trying to compile a exercise app statically, and it works nicely (having compiled QT for static libs and also adapted the QT environment, since some VS env vars interferred with errorfree compilation unless I removed the build environment, and I also added to the makespec the -static switch). So compiles work nicely. However, I use a toolbar with gfx in M$ .ico format, and these icons never show up in executables, only in the preview of the forms.
Following this short tuorial (added QTPLUGIN += qico, I don’t need to give the CONFIG += static since my QT environment is all static, however I tried that variant also, and I added to my main #include and Q_IMPORT_PLUGIN(qico).
But when building, I receive the error:
collect2: Id returned 1 exit status.
Since the QT Creator has only a very poor context help, I do not get any information from the ide about that error. What did I miss?
Addition:
Not having the slightest idea, what I am doing there (lol, well almost no idea), I modified my .pro with this line (having QT completely static):
QTPLUGINS += libqico
After all I already have that static versions of the plugins, libqico.a and libqicod.a. It compiled errorfree, however Icons on toolbar buttons still are not displayed.
Please disregard my two former Comments!
The solution for non-standard plugins compiled statically (in my special case this is qico) is like this:
in the .pro add this line:
LIBS += PATH\TO\qt\plugins\imageformats\libqico.a
This is the staically compiled version of qico.
in main.cpp add, like described in this article:
#include
Q_IMPORT_PLUGIN(qico)
This perfectly accesses statically linked icons in the app and displays them as expected.
This opens for me for 100% portable applications with no extra files.
Thank you for your brillant artivle that pushed me into the right direction!
I have another remark on statically linking QT projects:
When trying to add an application’s icon yesterday, it failed
whatever hints I tried.
RC_FILE and RES_FILE both failed, no matter what I did…
I am using QT Creator 1.3 and latest qt sdk plus mingw32 as maker.
Finally I found a post to create the res file using the -O coff option.
While before the build process failed with “unrecognized format” on the
res-file, it now suddenly worked like a charme!
So I created an rc file with my app icon, opened a QT prompt, and chdir’ed
to my project’s path. There I did a:
windres -O coff -i appico.rc -o appico.res
In my .pro I added RES_FILE += appico.res.
==> Perfect static build including the application icon.
I have a dynamic Qt installation. I want to use the imageformat plugins statically. I am using visual studio 2008. When I try to use the macro Q_IMPORT_PLUGIN(qgif) the compiler complains about “qgif”. How do I achieve this.
It seems the Qt libraries use libc.so.6 -> libc-2.11.1.so but my target (eurotech isis moblin atom sbc) uses libc.so.6 -> libc-2.6.1.so.
libc-2.11.1.so causes segmentation fault causes on this target on startup.
I put a libc.so.6 -> libc-2.11.1.so in the directory I run my app from and in /usr/lib but it still complains with the following error message:
/home/ume/myapp/: /lib/libc.so.6: version GLIBC_2.9 not found (required by /usr/lib/libQtGui.so.4)
/home/ume/myapp/: /lib/libc.so.6: version GLIBC_2.11 not found (required by /usr/lib/libQtGui.so.4)
/home/ume/myapp/: /lib/libc.so.6: version GLIBC_2.10 not found (required by /usr/lib/libQtNetwork.so.4)
/home/ume/myapp/: /lib/libc.so.6: version GLIBC_2.9 not found (required by /usr/lib/libQtCore.so.4)
Is there a way to include libc-2.11.1.so in the static link?
Thanks,
Jack
Hi folks
I’m pretty new to QT, been reading Charles articles and its darn clear, thumbs up.
After setting up my environment for static link, I was wondering if anyone can let me know how to determine which and what plugin to include in my pro and cpp? Please note I’m still new on QT, some kind words will be appreciated.
I’m not really clear from your description if I can use jpeg in a statically linked Qt or not. Is there a non-plugin version of the jpeg that can be used with a static link or can the jpeg plugin be statically linked?
The JPEG plugin itself can be statically linked. Essentially, a Qt program using the Qt JPEG plugin (or any other Qt plugin) can be distributed as one single executable file.
@Jon
This page has a list of plugins under “Static Plugins”: http://doc.trolltech.com/4.6/plugins-howto.html
If you are using any of the features listed from those plugins (for example, Oracle connectivity), then that plugin is needed.
Dear Charles,
Thank you very much for such a informative article.I am facing some issues during the build using mingw32-make. I can able to configure the Qt with configure -static and all but getting loads of the undefined references for uic3 during build process.
The another observation of mine is due this incomplete process..i am not able to compile and build the example projects of Qt. Please help…!!!
Gaurav Holey
Can you please tell me how can you detect which plugins (dll files) are needed to deploy an application on windows?
Application works fine on my computer and I have no “QTPLUGINS +=…” line in my .pro file
(I use qjpeg)
:: error: cannot find -lQtCored
I have this problem when I try to compile my project statically .
:: error: cannot find -lQtCored
I have this problem when I try to compile my project statically . How can I fix this ?
hi! I followed the steps for statically linking an app with QT. I think I got everything Almost right: When I compile a mini app , (just a window with a button) a get the exe (57kb) and 3 obj files of 1Mb+ in size each. I know It’s using the lib files (i renamed one and QT Creator showed errors while compiling) but it’s like it’s not mixing everything up into the exe file because it’s still asking for some QT***.dlls to run.
Any ideas??
THANKS!
Rodrigo,