Building Optimized Qt
This page describes the process of configuring and building a smaller and tailored version of Qt, according to your specific needs.
Step 1: Getting the Sources, and Installing Build Requirements and Set Environment
For getting sources, installing dependencies and setting up environment, refer to platform-specific instructions:
- Qt for Windows - Building from Source
- Qt for macOS - Building from Source
- Qt for Linux/X11 - Building from Source
- Configure an Embedded Linux Device
- Qt for Android - Building from Source
- Qt for iOS - Building from Source
Step 2: Building the Qt Libraries and Tools
Follow your platform-specific instructions and use the following Qt configure options to create a build that is optimized for your needs.
The following table describes in more detail the configure options that help to reduce build size.
| Qt configure option | Description |
|---|---|
| -static | Produce archive files for static linking. A static binary is linked with all necessary libraries and dependencies embedded within the executable file itself. This means that when you run the program, it uses its own internal copy of the required libraries, rather than relying on external ones. This allows linker to drop unnecessary parts of the binary code. This is the most optimal solution for single executable deliveries. |
| -ltcg | Link Time Optimization (LTO) is a powerful technique that can significantly improve the performance and reduce the size of your executable file by analyzing and optimizing binary code at the linking stage. |
| -reduce-exports | Reduce the amount of exported symbols. |
| -gc-binaries | Remove unnecessary parts from binary. Place each function or data item into its own section and enable linker garbage collection of unused sections. |
| -submodules qtbase,qtdeclarative,qtqmlscriptcompiler,qtsvg | Submodules to compile. Limit dependencies to unnecessary features. |
| -skip qtlanguageserver,qtquicktimeline | Remove automatically included submodules from compilation. Limit dependencies to unneeded features. |
| -disable-deprecated-up-to <version> | Remove deprecated implementation. Sets the QT_DISABLE_DEPRECATED_UP_TO value to <version>. QT_DISABLE_DEPRECATED_UP_TO is used to remove deprecated methods from both API and ABI. <version> is a hex value. For example, use 0x070000 to remove all code that is deprecated in Qt 7.0.0 or earlier releases. By default, <version> is set to 0x040000 and 0x050000 on Windows and non-Windows respectively. |
In addition, you can remove features one by one as described in Including or excluding features. This may cause restrictions for available components and functionalities. Not all combinations are tested. Qt tests a specific configure option combination in Continuous Integration (CI). This configure option combination is capable of running simple QML applications.
Qt configure command also supports the - - (double dash) command line parameter which allows user to inject extra CMake arguments such as -DCMAKE_CXX_FLAGS="-march=native". In case of cross compilation these parameters can be added via -DCMAKE_TOOLCHAIN_FILE=path/to/toolchain.cmake as described in An Example Toolchain File. The following table lists some options that you can consider using with GCC:
| Compiler option | Description |
|---|---|
| -march <arch> | Target architecture. Use "native" if application is executed on the same architecture where it's compiled. |
| -mtune <tune> | Tells the compiler to generate code that takes advantage of the specified processor architecture's characteristics, such as its instruction set, register count, and cache hierarchy. |
| -fno-asynchronous-unwind-tables | Reduces binary size. Keep in mind that disabling asynchronous unwind tables can have implications on performance, compatibility, and maintainability of your code. It's generally recommended to use this option only when necessary, after carefully considering its potential effects. |
| -fno-unwind-tables | Reduces binary size. Keep in mind that disabling unwind tables can have implications on performance, compatibility, and maintainability of your code. It's generally recommended to use this option only when necessary, after carefully considering its potential effects. It's worth noting that |
| -fomit-frame-pointer | Reduces binary size. When this option is enabled, the compiler doesn't store a frame pointer on the stack for each function call. Instead, it uses the stack pointer as the frame pointer, which can save memory and improve performance. It's worth noting that some compilers, such as GCC and Clang, enable -fomit-frame-pointer by default when compiling for certain architectures, such as ARM and PowerPC, or in certain optimization modes. |
| -fno-exceptions | Reduces binary size. When this option is enabled, the compiler doesn't generate code for try-catch blocks, and any attempts to throw or catch exceptions result in runtime errors. Qt itself works without exceptions, but some dependencies might require exceptions. |
| -no-pie | Reduces binary size. In general, -fno-pie should be used with caution and only when necessary, as it can have implications on the compatibility and performance of your compiled code. Position independent executable also adds security. For more information on position-independent code, refer to Address Space Layout Randomization in Wikipedia. |
The following table lists linker options:
| Linker option | Description |
|---|---|
| -no-pie | Reduces binary size. In general, -fno-pie should be used with caution and only when necessary, as it can have implications on the compatibility and performance of your compiled code. Position independent executable also adds security. For more information on position-independent code, refer to Address Space Layout Randomization in Wikipedia. |
Step 3: Building Your Application
After Qt is installed, you can start building applications with it.
Optimize QML code generation with CMake project commands. For more information on QML code generation, see qt_add_qml_module and Best Practices for QML and Qt Quick.
The command in the following CMake code snippet makes the binary size smaller:
set_target_properties(
ExampleApp
PROPERTIES
QT_QMLCACHEGEN_ARGUMENTS "--only-bytecode"
)If you plan to build your application from an IDE, you need to register the Qt version explicitly there. For Qt Creator, see Qt Creator: Adding Qt Versions.
If you're using command line to build your application, follow the platform-specific guide.
© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
