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:

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 `-fno-unwind-tables` is a more aggressive version of `-fno-asynchronous-unwind-tables`, as it disables the creation of unwind tables entirely, whereas the latter only disables the asynchronous generation of unwind tables.
-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 commands in the following CMake code snippet make the binary size smaller:

set_target_properties(
        ExampleApp
    PROPERTIES
        QT_QMLCACHEGEN_DIRECT_CALLS ON
        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.