Qt 5 (qt/qt5)

Qt 5

https://github.com/qt/qt5
Admin
Qt 6 is a cross-platform application development framework that enables developers to create native...

Tokens:7,210
Snippets:82
Trust Score:8
Update:11 months ago
Show doc for...
Context Summary (auto-generated)
Raw
# Qt5 Framework

Qt5 is a comprehensive cross-platform C++ application development framework for building desktop, mobile, and embedded applications. This repository serves as the meta-repository for the Qt5 framework, coordinating the build and dependency management across all Qt5 submodules including qtbase, qtdeclarative, qttools, qtwebengine, and dozens of other specialized modules for multimedia, networking, 3D graphics, and platform-specific functionality.

The framework uses a modular architecture where each submodule can be built independently or as part of the complete Qt5 suite. It supports multiple build configurations including release, debug, and developer builds, and provides flexible module selection allowing developers to build only the components they need. The repository includes configuration scripts, build tools, and initialization utilities that manage the complex dependency graph between modules.

## Initialize Repository

Initialize the Qt5 repository and clone all submodules from git.

This Perl script initializes a freshly cloned Qt5 repository by fetching all required submodules from their canonical URLs. It supports selective module initialization, mirror repositories, code review remote configuration, and various options for managing repository alternates and branch tracking.

```bash
# Initialize with default modules (essential, addon, preview, deprecated)
./init-repository

# Initialize only essential modules
./init-repository --module-subset=essential

# Initialize specific modules
./init-repository --module-subset=qtbase,qtdeclarative,qttools

# Initialize with mirror for faster cloning
./init-repository --mirror git://local-mirror/qt/

# Initialize for Gerrit code review with username
./init-repository --codereview-username=yourname

# Initialize excluding specific modules
./init-repository --module-subset=all,-qtwebengine,-qt3d

# Use alternates to save disk space (references another Qt5 checkout)
./init-repository --alternates /path/to/other/qt5/repo

# Check out submodule branches instead of specific commits
./init-repository --branch

# Quiet mode - exit cleanly if already initialized
./init-repository --quiet

# Force re-initialization
./init-repository --force
```

## Configure Build

Configure the Qt5 build system with platform-specific options and licensing.

This shell script serves as the entry point for configuring Qt5. It validates that submodules have been initialized, creates the qtbase build directory, and delegates to the actual configure script in qtbase with top-level build coordination.

```bash
# Configure for opensource development (Linux/Mac)
./configure -opensource -confirm-license -nomake tests

# Configure release build with custom prefix
./configure -prefix $PWD/qtbase -opensource -release -nomake tests -nomake examples

# Configure developer build (enables more tests, debug libraries)
./configure -developer-build -opensource -confirm-license

# Configure with specific features disabled
./configure -opensource -no-opengl -no-widgets -nomake examples

# Windows configuration (run in Visual Studio command prompt)
configure -opensource -confirm-license -nomake tests -platform win32-msvc

# Configure for static linking
./configure -opensource -static -nomake tests

# Configure with custom SSL
./configure -opensource -openssl-linked -I /usr/local/ssl/include -L /usr/local/ssl/lib

# Show all configuration options
./configure -help
```

## Build Framework

Build the configured Qt5 framework and selected modules.

After configuration, Qt5 uses standard make-based build system to compile all selected modules according to the dependency order defined in .gitmodules and qt.pro. The build system supports parallel compilation and selective module building.

```bash
# Build everything with 4 parallel jobs
make -j4

# Build specific module and its dependencies
make -j4 module-qtdeclarative

# Build only qtbase
cd qtbase && make -j4

# Build with MSVC on Windows (after configure)
nmake

# Build with jom (parallel nmake) on Windows
jom

# Build with MinGW on Windows
mingw32-make

# Clean build artifacts
make clean

# Build documentation
make docs

# Install built Qt5
make install
```

## Project Configuration

Define the supermodule build structure and submodule dependencies.

The qt.pro file is a QMake project file that parses .gitmodules to extract all Qt5 submodules, processes their dependencies and build order, handles module skipping via -skip command line arguments, and generates the appropriate build targets for the complete Qt5 framework.

```qmake
# qt.pro is automatically processed by qmake
# The following demonstrates how modules are organized:

# Skip modules during build (passed to configure/qmake)
# ./configure -skip qtwebengine -skip qt3d

# Module status values in .gitmodules:
# - essential: Core modules (qtbase, qtdeclarative)
# - addon: Additional functionality (qtmultimedia, qtnetworkauth)
# - preview: Preview/experimental modules
# - deprecated: Maintained but deprecated modules
# - obsolete: No longer maintained
# - ignore: Not built by default

# The build system automatically:
# 1. Reads .gitmodules to discover submodules
# 2. Extracts dependencies, recommends, and serialization
# 3. Sorts modules by dependency order
# 4. Creates build targets (module-qtbase, module-qtdeclarative, etc.)
# 5. Configures documentation generation

# Environment variables affecting build:
# QT_BUILD_MODULES: Only build specified modules
# QT_SKIP_MODULES: Skip specified modules
# QMAKE_EXTRA_ARGS: Additional qmake arguments
```

## Module Selection

Select which Qt5 modules to build based on categories and dependencies.

The init-repository script classifies modules into categories (essential, addon, preview, deprecated, obsolete, ignore) as defined in .gitmodules. Users can specify subsets using category names, individual module names, or exclude modules with a dash prefix.

```bash
# Module categories and examples:
# essential: qtbase, qtdeclarative, qttools
# addon: qtmultimedia, qtnetworkauth, qtcharts, qtserialport
# preview: qtlottie, qtquick3d (newer/experimental features)
# deprecated: qtscript, qtquickcontrols (Qt Quick Controls 1)
# obsolete: qtpim, qtdocgallery, qtsystems

# Initialize only essential modules (minimal Qt)
./init-repository --module-subset=essential

# Initialize essential + specific addons
./init-repository --module-subset=essential,qtmultimedia,qtnetworkauth

# Initialize everything except obsolete
./init-repository --module-subset=all,-obsolete,-ignore

# Initialize for embedded development
./init-repository --module-subset=essential,qtserialbus,qtserialport

# Initialize for desktop GUI applications
./init-repository --module-subset=essential,addon,-qtwebengine

# Initialize for Qt Quick development
./init-repository --module-subset=qtbase,qtdeclarative,qtquickcontrols2,qtgraphicaleffects

# Check submodule status values
git config -l -f .gitmodules | grep "submodule\\..*\\.status"
```

## Build System Requirements

System and toolchain requirements for building Qt5.

Qt5 requires modern development tools including Perl for the initialization scripts, Python for build utilities, a C++11 compliant compiler, and platform-specific build tools. The exact requirements vary by platform and target configuration.

```bash
# Verify Perl installation (required: 5.8+)
perl --version

# Verify Python installation (required: 2.7+ or 3.x)
python --version

# Linux: Install build dependencies (Debian/Ubuntu example)
sudo apt-get install build-essential perl python git
sudo apt-get install libgl1-mesa-dev libxcb-xinerama0-dev

# Linux: Check GCC version (need C++11 support, GCC 4.9+)
gcc --version
g++ --version

# Mac: Install Xcode command line tools
xcode-select --install

# Mac: Verify compiler
clang --version

# Windows: Visual Studio 2012 or later required
# Ensure cl.exe, nmake/jom, perl, python in PATH

# Windows: Check tools availability
where cl
where nmake
where perl
where python

# Windows: For MinGW builds (MinGW-builds 4.9+)
where mingw32-make
where g++

# Additional platform-specific requirements at:
# http://wiki.qt.io/Get_The_Source
```

## Summary

Qt5 is designed for cross-platform application development with support for desktop (Windows, macOS, Linux), mobile (iOS, Android), and embedded systems. The framework's modular architecture allows developers to build minimal configurations for embedded devices or full-featured desktop application stacks. Common use cases include creating native desktop applications with Qt Widgets, developing modern fluid UIs with Qt Quick/QML, building multimedia applications, implementing network services, creating embedded device interfaces, and developing cross-platform mobile applications.

The build system integrates with standard development workflows through configure/make on Unix-like systems and configure/nmake on Windows. Developers can integrate Qt5 into existing projects, contribute to Qt development through the Gerrit code review system, maintain multiple Qt5 checkouts with different configurations, and build custom Qt5 configurations tailored to specific deployment requirements. The framework supports both open source (LGPL/GPL) and commercial licensing, providing flexibility for various project types from open source applications to proprietary commercial software.