개발 스택 가이드 · Qt

Qt 개발.

현재 안정 Qt 릴리스를 source에서 host/target SDK를 분리해 build하세요. 이 페이지의 버전 의존 명령은 Qt 공식 index와 최신 플랫폼 문서에서 갱신되는 release manifest를 기반으로 생성됩니다.

현재 Qt 6.12.0 Qt Creator 20.0.2 최소 CMake 3.25 갱신됨 Oct 11, 2026 10:54 UTC

hard-code된 가이드 버전이 아니라 현재 안정 릴리스를 따르세요.

release 번호, source archive 이름, 문서 시리즈, Qt Creator 버전, Android 호환성 값, Emscripten target을 중앙에서 해결합니다. Qt가 새 안정 릴리스를 배포하면 각 페이지를 수동 수정하지 않고 generated path와 compatibility snapshot을 갱신합니다.

단일 소스를 기준으로 사용하세요.

upstream 요구사항이 바뀌면 새 버전 번호를 본문에 복사하지 말고 release resolver를 갱신하세요. 안전하게 추론할 수 없는 플랫폼 정보는 현재 공식 Qt platform matrix에 연결해 둡니다.

source, build, install tree를 분리하세요.

Do not build inside the source tree and do not mix host and target installations. A neutral host prefix works on macOS, Linux or Windows; cross-compiled targets live beside it.

LayoutCurrent release

~/Qt/
├── Src/
│   └── qt-everywhere-src-6.12.0/
├── Build/
│   └── 6.12.0/
│       ├── host/
│       ├── linux-x86_64/
│       ├── linux-arm64/
│       ├── linux-armv7/
│       ├── rpi-aarch64/
│       ├── android-arm64-v8a/
│       ├── android-armeabi-v7a/
│       ├── android-x86_64/
│       ├── android-x86/
│       ├── ios/
│       ├── ios-device/
│       ├── ios-simulator/
│       ├── wasm/
│       └── wasm-threads-simd/
├── 6.12.0/
│   ├── host/
│   ├── linux-x86_64/
│   ├── linux-arm64/
│   ├── linux-armv7/
│   ├── rpi-aarch64/
│   ├── android-arm64-v8a/
│   ├── android-armeabi-v7a/
│   ├── android-x86_64/
│   ├── android-x86/
│   ├── ios/
│   ├── ios-device/
│   ├── ios-simulator/
│   ├── wasm/
│   └── wasm-threads-simd/
└── Toolchains/
    └── emsdk/

현재 안정 source archive를 받으세요.

아래 archive URL은 Qt의 현재 stable release index에서 생성됩니다.

ShellDownload and extract

mkdir -p "$HOME/Qt/Src"
cd "$HOME/Qt/Src"

curl -fLO "https://download.qt.io/official_releases/qt/6.12/6.12.0/single/qt-everywhere-src-6.12.0.tar.xz"
tar -xf "qt-everywhere-src-6.12.0.tar.xz"

현재 target matrix.

Target	Current compatibility snapshot	Build rule
macOS	Xcode 16+	Native Apple toolchain; universal builds are optional.
Linux	Ubuntu 24.04 / Debian 11.6–12 · x86_64, arm64	Native x86_64 and arm64 are in the current supported desktop matrix; additional embedded Linux architectures require a matching toolchain and sysroot.
Embedded Linux	Raspberry Pi, Jetson, Orange Pi, BeagleBone, RISC-V boards	Use a host Qt, board-matching cross compiler, sysroot and CMake toolchain file.
Windows	MSVC 2022 · Mingw-w64 15.1	MSVC와 MinGW의 prefix 및 build tree를 분리하세요.
Android	Android 9–16 · API 28–36 · arm64-v8a, armeabi-v7a, x86_64, x86	Build a host Qt first, then keep each Android ABI in its own build and install tree.
iOS	Xcode 16+ · iOS 18+	macOS에서 build하고 device/simulator 지원은 iOS target SDK에 유지하세요.
WebAssembly	Emscripten 5.0.5	일치하는 host Qt를 먼저 build하고 single-threaded/threaded variant를 분리하세요.

For exact architecture and distribution rows, use the current Qt supported-platforms matrix ↗. This guide intentionally avoids duplicating long-lived platform tables that upstream owns.

Desktop host

먼저 host Qt를 build하세요.

Android, iOS, WebAssembly source build에는 동일 release의 host-side Qt tools가 필요합니다. cross-compilation target 전에 host SDK를 build하고 verify하세요.

macOS host

ShellPrepare

sudo xcode-select --switch /Applications/Xcode.app
sudo xcodebuild -license accept

brew install cmake ninja python bison flex gperf node pkg-config

cmake --version
ninja --version
xcrun clang++ --version

ShellConfigure and build host Qt

mkdir -p "$HOME/Qt/Build/6.12.0/host"
cd "$HOME/Qt/Build/6.12.0/host"

"$HOME/Qt/Src/qt-everywhere-src-6.12.0/configure" \
  -prefix "$HOME/Qt/6.12.0/host" \
  -release \
  -shared \
  -make examples

cmake --build . --parallel
cmake --install .

Linux host

ShellUbuntu / Debian baseline

sudo apt update
sudo apt install -y \
  build-essential \
  clang \
  cmake \
  ninja-build \
  pkg-config \
  python3 \
  bison \
  flex \
  gperf \
  nodejs

Add the X11/Wayland, OpenGL/Vulkan, multimedia, accessibility and other development packages required by the modules you intend to build. Qt's configure summary is authoritative: do not ignore a disabled feature you actually need.

Windows host

Use a Developer PowerShell for the current supported MSVC toolchain, with CMake and Ninja visible in the same environment.

PowerShellConfigure and build

mkdir C:\Qt\build\6.12.0\host
cd C:\Qt\build\6.12.0\host

C:\\Qt\\Src\\qt-everywhere-src-6.12.0\\configure.bat `
  -prefix C:\\Qt\\6.12.0\\host `
  -release `
  -shared `
  -make examples

cmake --build . --parallel
cmake --install .

Desktop · macOS

선택적 universal macOS SDK.

하나의 Qt installation에 Intel과 Apple Silicon slice가 모두 필요하면 native host build를 변경하지 말고 별도 universal prefix를 만드세요.

Shellx86_64 + arm64

mkdir -p "$HOME/Qt/Build/6.12.0/macos-universal"
cd "$HOME/Qt/Build/6.12.0/macos-universal"

"$HOME/Qt/Src/qt-everywhere-src-6.12.0/configure" \
  -prefix "$HOME/Qt/6.12.0/macos-universal" \
  -release \
  -shared \
  -- \
  -DCMAKE_OSX_ARCHITECTURES="x86_64;arm64"

cmake --build . --parallel
cmake --install .

Desktop & Embedded · Linux

Linux architectures.

Qt's current supported desktop matrix covers x86_64 and arm64 on current Ubuntu and Debian releases. Other Linux architectures can still be built from source when you provide a matching cross compiler and sysroot, but they are not equivalent to the officially supported desktop configurations.

Architecture	Build mode	Support level
`x86_64`	Native desktop	Current supported Linux desktop architecture
`arm64 / aarch64`	Native desktop or cross-compiled	Current supported Linux desktop architecture on listed Ubuntu/Debian releases
`armv7 / armhf`	Cross-compiled embedded Linux	Requires target-specific toolchain, sysroot and device validation
`riscv64`	Cross-compiled embedded/custom Linux	Possible with a working toolchain/sysroot; not in the current mainstream desktop matrix

Native x86_64

Use this on a 64-bit Intel/AMD Linux host. Keep the install prefix architecture-specific so it never collides with ARM builds.

ShellLinux x86_64

mkdir -p "$HOME/Qt/Build/6.12.0/linux-x86_64"
cd "$HOME/Qt/Build/6.12.0/linux-x86_64"

"$HOME/Qt/Src/qt-everywhere-src-6.12.0/configure" \
  -prefix "$HOME/Qt/6.12.0/linux-x86_64" \
  -release \
  -shared \
  -make examples

cmake --build . --parallel
cmake --install .

Native arm64 / aarch64

On an ARM64 Linux machine, build natively exactly as you would on x86_64. Qt currently lists Ubuntu 24.04 and Debian 11.6/12 ARM64 in the supported Linux matrix.

ShellLinux arm64

mkdir -p "$HOME/Qt/Build/6.12.0/linux-arm64"
cd "$HOME/Qt/Build/6.12.0/linux-arm64"

"$HOME/Qt/Src/qt-everywhere-src-6.12.0/configure" \
  -prefix "$HOME/Qt/6.12.0/linux-arm64" \
  -release \
  -shared \
  -make examples

cmake --build . --parallel
cmake --install .

Cross-compile x86_64 host → arm64 target

Cross-compiling Qt for Linux requires a host Qt of the same release, a target sysroot and a CMake toolchain file. The example below uses the conventional aarch64-linux-gnu toolchain; replace the sysroot with the one that belongs to your actual target distribution or device.

On Ubuntu or Debian, install the matching cross compilers for the architectures you intend to build: gcc-aarch64-linux-gnu, g++-aarch64-linux-gnu, gcc-arm-linux-gnueabihf and g++-arm-linux-gnueabihf.

CMakelinux-aarch64-toolchain.cmake

set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR aarch64)

set(CMAKE_SYSROOT "/opt/sysroots/aarch64-linux-gnu")
set(CMAKE_C_COMPILER aarch64-linux-gnu-gcc)
set(CMAKE_CXX_COMPILER aarch64-linux-gnu-g++)

set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)

ShellCross-build arm64

mkdir -p "$HOME/Qt/Build/6.12.0/linux-arm64"
cd "$HOME/Qt/Build/6.12.0/linux-arm64"

"$HOME/Qt/Src/qt-everywhere-src-6.12.0/configure" \
  -release \
  -qt-host-path "$HOME/Qt/6.12.0/host" \
  -extprefix "$HOME/Qt/6.12.0/linux-arm64" \
  -prefix "/usr/local/qt6" \
  -nomake tests \
  -- \
  -DCMAKE_TOOLCHAIN_FILE="$HOME/Qt/Toolchains/linux-aarch64-toolchain.cmake"

cmake --build . --parallel
cmake --install .

Cross-compile x86_64 host → ARMv7 hard-float

ARMv7 is useful for older embedded Linux devices and 32-bit ARM boards. It is a cross-compiled embedded target, not part of the current mainstream Linux desktop support matrix. Use the sysroot and compiler that match the device image exactly.

CMakelinux-armv7-toolchain.cmake

set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR arm)

set(CMAKE_SYSROOT "/opt/sysroots/arm-linux-gnueabihf")
set(CMAKE_C_COMPILER arm-linux-gnueabihf-gcc)
set(CMAKE_CXX_COMPILER arm-linux-gnueabihf-g++)

set(CMAKE_C_FLAGS_INIT "-march=armv7-a -mfpu=neon -mfloat-abi=hard")
set(CMAKE_CXX_FLAGS_INIT "-march=armv7-a -mfpu=neon -mfloat-abi=hard")

set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)

ShellCross-build ARMv7

mkdir -p "$HOME/Qt/Build/6.12.0/linux-armv7"
cd "$HOME/Qt/Build/6.12.0/linux-armv7"

"$HOME/Qt/Src/qt-everywhere-src-6.12.0/configure" \
  -release \
  -qt-host-path "$HOME/Qt/6.12.0/host" \
  -extprefix "$HOME/Qt/6.12.0/linux-armv7" \
  -prefix "/usr/local/qt6" \
  -nomake tests \
  -- \
  -DCMAKE_TOOLCHAIN_FILE="$HOME/Qt/Toolchains/linux-armv7-toolchain.cmake"

cmake --build . --parallel
cmake --install .

Other Linux architectures.

The same Qt 6 cross-compilation model also applies to architectures such as riscv64 when a working compiler, sysroot and graphics/input stack exist. Treat these as target-specific embedded builds unless the current Qt supported-platforms matrix explicitly lists them.

Embedded Linux · SBC

Raspberry Pi and other Linux boards.

Qt 6 uses the same cross-compilation model for Raspberry Pi and other Linux boards: a host Qt of the same release, a cross compiler, a sysroot that exactly matches the target image, and a CMake toolchain file. The old Qt 5 device-mkspec-only workflow is not sufficient for Qt 6.

Board family	Typical architecture	Notes
Raspberry Pi 5 / Raspberry Pi 4 · 64-bit OS	`aarch64 / arm64`	Recommended path for current Raspberry Pi OS and modern embedded deployments.
Raspberry Pi 4 / older Pi · 32-bit OS	`armv7 / armhf`	Use the ARMv7 hard-float toolchain and a matching 32-bit sysroot.
NVIDIA Jetson family	`aarch64`	Use the JetPack/L4T-compatible sysroot so EGL, OpenGL ES and vendor libraries match the device.
Orange Pi / Rockchip boards	`aarch64` or `armv7`	Architecture depends on the SoC and installed Linux image.
BeagleBone Black	`armv7 / armhf`	Usually cross-compiled with `arm-linux-gnueabihf`.
RISC-V development boards	`riscv64`	Requires a target-specific compiler, sysroot and graphics/input stack.

Raspberry Pi 4 / 5 · 64-bit example

Prefer an SDK or sysroot produced from the exact operating-system image running on the board. A sysroot copied from a different Raspberry Pi OS or distro revision can configure successfully and still fail later because EGL, Mesa, libc or other target libraries do not match.

ShellHost cross-compiler baseline

sudo apt update
sudo apt install -y \
  gcc-aarch64-linux-gnu \
  g++-aarch64-linux-gnu \
  cmake \
  ninja-build \
  pkg-config

export RPI_SYSROOT="$HOME/Qt/Sysroots/rpi-aarch64"
export QT_HOST="$HOME/Qt/6.12.0/host"

CMakerpi-aarch64-toolchain.cmake

set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR aarch64)

set(CMAKE_SYSROOT "$ENV{RPI_SYSROOT}")

set(CMAKE_C_COMPILER aarch64-linux-gnu-gcc)
set(CMAKE_CXX_COMPILER aarch64-linux-gnu-g++)

set(CMAKE_FIND_ROOT_PATH "$ENV{RPI_SYSROOT}")
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)

ShellBuild Qt Base for Raspberry Pi

export RPI_SYSROOT="$HOME/Qt/Sysroots/rpi-aarch64"
export QT_HOST="$HOME/Qt/6.12.0/host"

mkdir -p "$HOME/Qt/Build/6.12.0/rpi-aarch64"
cd "$HOME/Qt/Build/6.12.0/rpi-aarch64"

"$HOME/Qt/Src/qt-everywhere-src-6.12.0/qtbase/configure" \
  -release \
  -opengl es2 \
  -qt-host-path "$QT_HOST" \
  -extprefix "$HOME/Qt/6.12.0/rpi-aarch64" \
  -prefix "/usr/local/qt6" \
  -nomake examples \
  -nomake tests \
  -- \
  -DCMAKE_TOOLCHAIN_FILE="$HOME/Qt/Toolchains/rpi-aarch64-toolchain.cmake"

cmake --build . --parallel
cmake --install .

Graphics support comes from the target sysroot.

For Raspberry Pi, Jetson and similar boards, check the configure summary for the platform integration you actually need: EGLFS, Wayland, OpenGL ES or another QPA backend. A successful compiler test alone does not prove that the target graphics stack is usable.

Deploy and verify on the board

ShellExample deployment

rsync -a --delete \
  "$HOME/Qt/6.12.0/rpi-aarch64/" \
  user@raspberrypi:/usr/local/qt6/

ssh user@raspberrypi \
  '/usr/local/qt6/bin/qtpaths --qt-version'

For a 32-bit Raspberry Pi image or BeagleBone-class target, use the ARMv7 toolchain shown in the Linux architecture section and keep a separate rpi-armv7 or device-specific installation prefix.

Mobile · Android

Android.

The current manifest resolves Android 9–16, API 28–36, Build Tools 36.0.0, NDK r27c (27.2.12479018), JDK 21, Gradle 9.5.1 and AGP 9.2.1 from Qt's current documentation.

ShellInstall current Qt-compatible Android components

sdkmanager \
  "platform-tools" \
  "platforms;android-36" \
  "build-tools;36.0.0" \
  "ndk;27.2.12479018"

macOS · arm64-v8a

This is the verified source-build path on macOS when Android Studio or the Android command-line tools installed the SDK in its standard location.

ShellConfigure Qt for Android

mkdir -p "$HOME/Qt/Build/6.12.0/android-arm64-v8a"
cd "$HOME/Qt/Build/6.12.0/android-arm64-v8a"

"$HOME/Qt/Src/qt-everywhere-src-6.12.0/configure" \
  -prefix "$HOME/Qt/6.12.0/android-arm64-v8a" \
  -qt-host-path "$HOME/Qt/6.12.0/host" \
  -android-abis arm64-v8a \
  -android-sdk "$HOME/Library/Android/sdk" \
  -android-ndk "$HOME/Library/Android/sdk/ndk/27.2.12479018" \
  -release

ShellBuild and install

cmake --build . --parallel
cmake --install .

Supported Android ABIs

ABI	Typical use	Suggested Qt prefix
`arm64-v8a`	Primary 64-bit ARM phones and tablets	`android-arm64-v8a`
`armeabi-v7a`	Older 32-bit ARM devices	`android-armeabi-v7a`
`x86_64`	64-bit x86 Android emulators and compatible devices	`android-x86_64`
`x86`	Legacy 32-bit x86 emulator/device coverage	`android-x86`

macOS · armeabi-v7a

Shell32-bit ARM Android

mkdir -p "$HOME/Qt/Build/6.12.0/android-armeabi-v7a"
cd "$HOME/Qt/Build/6.12.0/android-armeabi-v7a"

"$HOME/Qt/Src/qt-everywhere-src-6.12.0/configure" \
  -prefix "$HOME/Qt/6.12.0/android-armeabi-v7a" \
  -qt-host-path "$HOME/Qt/6.12.0/host" \
  -android-abis armeabi-v7a \
  -android-sdk "$HOME/Library/Android/sdk" \
  -android-ndk "$HOME/Library/Android/sdk/ndk/27.2.12479018" \
  -release

cmake --build . --parallel
cmake --install .

macOS · x86_64

Shell64-bit x86 Android

mkdir -p "$HOME/Qt/Build/6.12.0/android-x86_64"
cd "$HOME/Qt/Build/6.12.0/android-x86_64"

"$HOME/Qt/Src/qt-everywhere-src-6.12.0/configure" \
  -prefix "$HOME/Qt/6.12.0/android-x86_64" \
  -qt-host-path "$HOME/Qt/6.12.0/host" \
  -android-abis x86_64 \
  -android-sdk "$HOME/Library/Android/sdk" \
  -android-ndk "$HOME/Library/Android/sdk/ndk/27.2.12479018" \
  -release

cmake --build . --parallel
cmake --install .

Optional legacy x86 build

Shell32-bit x86 Android

mkdir -p "$HOME/Qt/Build/6.12.0/android-x86"
cd "$HOME/Qt/Build/6.12.0/android-x86"

"$HOME/Qt/Src/qt-everywhere-src-6.12.0/configure" \
  -prefix "$HOME/Qt/6.12.0/android-x86" \
  -qt-host-path "$HOME/Qt/6.12.0/host" \
  -android-abis x86 \
  -android-sdk "$HOME/Library/Android/sdk" \
  -android-ndk "$HOME/Library/Android/sdk/ndk/27.2.12479018" \
  -release

cmake --build . --parallel
cmake --install .

First configure may spend time resolving Gradle dependencies.

Qt may download Gradle 9.5.1 and the Android Gradle Plugin 9.2.1 during dependency resolution. A Gradle BUILD SUCCESSFUL message means that dependency-resolution stage completed successfully; Qt's top-level configure must still finish without a later CMake error before the build tree is considered ready.

If Gradle times out

Populate Qt's Gradle cache explicitly, then rerun the configure command above. This keeps the actual Qt build offline with respect to Gradle dependencies.

ShellResolve Gradle dependencies once

QT_SRC="$HOME/Qt/Src/qt-everywhere-src-6.12.0"

cmake -E env \
  ANDROID_SDK_ROOT="$HOME/Library/Android/sdk" \
  cmake \
  -DACTION_RESOLVE_GRADLE=ON \
  -DQT_ROOT_DIR="$QT_SRC/qtbase" \
  -DGRADLE_PROJECT_DIR="$QT_SRC/qtbase/src/android/jar" \
  -DGRADLE_BUILD_VARIANT=Release \
  -DQT_ANDROID_SDK_BUILD_TOOLS_REVISION=36.0.0 \
  -P "$QT_SRC/qtbase/cmake/QtSetupAndroid.cmake"

Other host platforms

The configure arguments are the same; only the Android SDK path changes. Common SDK locations are ~/Android/Sdk on Linux, ~/Library/Android/sdk on macOS and C:\Users\<USER>\AppData\Local\Android\Sdk on Windows. Keep the host Qt path and Android target installation separate.

POSIX shellPortable SDK variables

export ANDROID_SDK_ROOT="/path/to/Android/Sdk"
export ANDROID_NDK_ROOT="$ANDROID_SDK_ROOT/ndk/27.2.12479018"

"$HOME/Qt/Src/qt-everywhere-src-6.12.0/configure" \
  -prefix "$HOME/Qt/6.12.0/android-arm64-v8a" \
  -qt-host-path "$HOME/Qt/6.12.0/host" \
  -android-abis arm64-v8a \
  -android-sdk "$ANDROID_SDK_ROOT" \
  -android-ndk "$ANDROID_NDK_ROOT" \
  -release

Multi-ABI application packages

Build Qt once per ABI, then let the application build combine the installed Qt SDKs into a multi-ABI APK, AAB or AAR. Because these source-built prefixes use explicit names, pass their paths to CMake instead of relying on installer-directory autodetection.

Shellarm64-v8a + armeabi-v7a + x86_64

"$HOME/Qt/6.12.0/android-arm64-v8a/bin/qt-cmake" \
  -S /path/to/app \
  -B /path/to/app-build \
  -GNinja \
  -DANDROID_SDK_ROOT="$HOME/Library/Android/sdk" \
  -DANDROID_NDK_ROOT="$HOME/Library/Android/sdk/ndk/27.2.12479018" \
  -DQT_ANDROID_ABIS="arm64-v8a;armeabi-v7a;x86_64" \
  -DQT_PATH_ANDROID_ABI_arm64-v8a="$HOME/Qt/6.12.0/android-arm64-v8a" \
  -DQT_PATH_ANDROID_ABI_armeabi-v7a="$HOME/Qt/6.12.0/android-armeabi-v7a" \
  -DQT_PATH_ANDROID_ABI_x86_64="$HOME/Qt/6.12.0/android-x86_64"

cmake --build /path/to/app-build --target apk
# or:
cmake --build /path/to/app-build --target aab

Use only the ABIs your product needs. Keeping each Qt ABI in its own prefix makes upgrades, verification and multi-ABI packaging deterministic.

Mobile · iOS

iOS device and Simulator.

iOS builds run on macOS and use the Apple SDK supplied by the current Xcode toolchain. The current compatibility snapshot requires Xcode 16+ and iOS 18+. The device architecture is arm64; the simulator architecture resolved from the current Qt documentation is x86_64.

Target	SDK	Architecture	Install prefix
Device	`iphoneos`	`arm64`	`ios-device`
Simulator	`iphonesimulator`	`x86_64`	`ios-simulator`
Combined Qt SDK	Device + Simulator	Qt-managed	`ios`

Default: build one Qt for iOS SDK containing device and Simulator libraries

Qt's default iOS source build includes both device and Simulator libraries. Use this when a single Qt installation should drive both Xcode run destinations.

ShellCombined iOS SDK

mkdir -p "$HOME/Qt/Build/6.12.0/ios"
cd "$HOME/Qt/Build/6.12.0/ios"

"$HOME/Qt/Src/qt-everywhere-src-6.12.0/configure" \
  -platform macx-ios-clang \
  -qt-host-path "$HOME/Qt/6.12.0/host" \
  -prefix "$HOME/Qt/6.12.0/ios" \
  -release

cmake --build . --parallel
cmake --install .

Device-only SDK

용도 -sdk iphoneos when you want a dedicated physical-device Qt installation.

Shelliphoneos · arm64

mkdir -p "$HOME/Qt/Build/6.12.0/ios-device"
cd "$HOME/Qt/Build/6.12.0/ios-device"

"$HOME/Qt/Src/qt-everywhere-src-6.12.0/configure" \
  -platform macx-ios-clang \
  -sdk iphoneos \
  -qt-host-path "$HOME/Qt/6.12.0/host" \
  -prefix "$HOME/Qt/6.12.0/ios-device" \
  -release

cmake --build . --parallel
cmake --install .

Simulator-only SDK

용도 -sdk iphonesimulator for a dedicated Simulator Qt installation.

Shelliphonesimulator · x86_64

mkdir -p "$HOME/Qt/Build/6.12.0/ios-simulator"
cd "$HOME/Qt/Build/6.12.0/ios-simulator"

"$HOME/Qt/Src/qt-everywhere-src-6.12.0/configure" \
  -platform macx-ios-clang \
  -sdk iphonesimulator \
  -qt-host-path "$HOME/Qt/6.12.0/host" \
  -prefix "$HOME/Qt/6.12.0/ios-simulator" \
  -release

cmake --build . --parallel
cmake --install .

Apple Silicon: the current Qt iOS Simulator libraries are x86_64.

The Simulator run destination therefore uses Rosetta on Apple Silicon Macs. With Xcode 26 or newer, install the universal iOS platform component if the Rosetta-based Simulator destination is missing:

ShellXcode 26+

xcodebuild -downloadPlatform iOS -architectureVariant universal

Build an application

Use the qt-cmake from the selected iOS Qt prefix. The generated Xcode project can then run on the physical device or Simulator destination represented by that SDK.

ShellSimulator application

"$HOME/Qt/6.12.0/ios-simulator/bin/qt-cmake" \
  -S /path/to/app \
  -B /path/to/app-build-ios-simulator \
  -G Xcode

cmake --build /path/to/app-build-ios-simulator \
  --config Release

Do not manually force a different Simulator architecture unless the current Qt iOS documentation explicitly supports it. The release manifest tracks the Simulator architecture from Qt's current upstream documentation.

Web · WebAssembly

WebAssembly.

Each Qt minor release targets a specific Emscripten version. The current resolver pins 5.0.5. Use that exact version for the baseline build and keep the emsdk installation isolated from unrelated Emscripten projects.

macOS / Linux: install and activate the matching Emscripten SDK

POSIX shellInstall · activate · verify

export EMSCRIPTEN_VERSION="5.0.5"
export EMSDK_ROOT="$HOME/Qt/Toolchains/emsdk"

mkdir -p "$HOME/Qt/Toolchains"

if [ ! -d "$EMSDK_ROOT/.git" ]; then
  git clone https://github.com/emscripten-core/emsdk.git "$EMSDK_ROOT"
fi

cd "$EMSDK_ROOT"

./emsdk install "$EMSCRIPTEN_VERSION"
./emsdk activate "$EMSCRIPTEN_VERSION"

test -f "$EMSDK_ROOT/.emscripten" || {
  echo "Emscripten activation failed: $EMSDK_ROOT/.emscripten is missing" >&2
  exit 1
}

source "$EMSDK_ROOT/emsdk_env.sh"

command -v em++
em++ --version
em++ --version | grep -F "$EMSCRIPTEN_VERSION"

install and activate are two separate commands.

If they are accidentally pasted together, the SDK is not activated and .emscripten is not created. Sourcing emsdk_env.sh alone is not enough. Qt reads $EMSDK/.emscripten during WebAssembly auto-detection.

Repair an emsdk checkout that shows `.emscripten: No such file or directory`

POSIX shellRepair the active SDK

export EMSCRIPTEN_VERSION="5.0.5"
cd "$HOME/Qt/Toolchains/emsdk"

./emsdk install "$EMSCRIPTEN_VERSION"
./emsdk activate "$EMSCRIPTEN_VERSION"
source ./emsdk_env.sh

test -f "$EMSDK/.emscripten"
em++ --version
em++ --version | grep -F "$EMSCRIPTEN_VERSION"

If em++ --version still reports a different development version such as *-git, do not continue with the baseline Qt build. Re-run activate, source the environment again, and verify the version before configuring Qt.

Windows PowerShell installation

Run this block only in PowerShell on Windows. Do not paste Set-Location, .bat or .ps1 commands into zsh/bash on macOS or Linux.

PowerShellWindows · install · activate · verify

$env:EMSCRIPTEN_VERSION = "5.0.5"
$emsdkRoot = "$HOME\Qt\Toolchains\emsdk"

if (-not (Test-Path "$emsdkRoot\.git")) {
    git clone https://github.com/emscripten-core/emsdk.git $emsdkRoot
}

Set-Location $emsdkRoot

.\emsdk.bat install $env:EMSCRIPTEN_VERSION
.\emsdk.bat activate $env:EMSCRIPTEN_VERSION
.\emsdk_env.ps1

em++ --version

Baseline single-threaded SDK

After a failed configure, remove the incomplete build tree before trying again. A failed configure does not create a usable build.ninja or cmake_install.cmake.

ShellConfigure and build

export EMSCRIPTEN_VERSION="5.0.5"
export EMSDK_ROOT="$HOME/Qt/Toolchains/emsdk"

cd "$EMSDK_ROOT"
./emsdk activate "$EMSCRIPTEN_VERSION"
source "$EMSDK_ROOT/emsdk_env.sh"

test -f "$EMSDK_ROOT/.emscripten"
em++ --version | grep -F "$EMSCRIPTEN_VERSION"

rm -rf "$HOME/Qt/Build/6.12.0/wasm"
mkdir -p "$HOME/Qt/Build/6.12.0/wasm"
cd "$HOME/Qt/Build/6.12.0/wasm"

"$HOME/Qt/Src/qt-everywhere-src-6.12.0/configure" \
  -qt-host-path "$HOME/Qt/6.12.0/host" \
  -platform wasm-emscripten \
  -prefix "$HOME/Qt/6.12.0/wasm" \
  -release

cmake --build . --parallel
cmake --install .

Threads + SIMD build

ShellPerformance-oriented variant

export EMSCRIPTEN_VERSION="5.0.5"
export EMSDK_ROOT="$HOME/Qt/Toolchains/emsdk"

cd "$EMSDK_ROOT"
./emsdk activate "$EMSCRIPTEN_VERSION"
source "$EMSDK_ROOT/emsdk_env.sh"

test -f "$EMSDK_ROOT/.emscripten"
em++ --version | grep -F "$EMSCRIPTEN_VERSION"

rm -rf "$HOME/Qt/Build/6.12.0/wasm-threads-simd"
mkdir -p "$HOME/Qt/Build/6.12.0/wasm-threads-simd"
cd "$HOME/Qt/Build/6.12.0/wasm-threads-simd"

"$HOME/Qt/Src/qt-everywhere-src-6.12.0/configure" \
  -qt-host-path "$HOME/Qt/6.12.0/host" \
  -platform wasm-emscripten \
  -prefix "$HOME/Qt/6.12.0/wasm-threads-simd" \
  -release \
  -feature-thread \
  -feature-wasm-simd128

cmake --build . --parallel
cmake --install .

브라우저 capability도 toolchain의 일부입니다.

Threaded WebAssembly에는 cross-origin isolation과 secure context가 필요합니다. SIMD, exceptions, dynamic linking, Asyncify는 현재 Qt WebAssembly 문서와 실제 대상 브라우저에서 검증해야 합니다.

“전체 Qt”가 의미하는 것.

Use the complete Qt source package and avoid -skip unless a module is intentionally excluded. Qt still builds only modules supported by the current target and whose external dependencies are satisfied. A desktop host, Android, iOS and WebAssembly are separate SDKs and do not expose identical module sets.

Read the configure summary.

명령이 성공했다고 충분한 것은 아닙니다. 필요한 feature가 누락된 system dependency 때문에 조용히 비활성화됐다면 configuration failure입니다. 예상치 못하게 비활성화된 feature를 모두 오류로 취급하세요.

Modern Qt 프로젝트는 Modern C++ 프로젝트로 유지됩니다.

Qt를 쓴다고 header-first architecture나 오래된 console idiom으로 돌아갈 이유는 없습니다. domain/application code를 project modules에 두고 Qt Quick/QML을 presentation adapter로 사용하며 C++/QML 경계를 명시하세요.

CMakeModule-based Qt Quick baseline

cmake_minimum_required(VERSION 3.30)

project(GenyleapSample
    VERSION 0.1.0
    LANGUAGES CXX
)

add_library(genyleap_sample_core)

target_compile_features(genyleap_sample_core
    PUBLIC
        cxx_std_26
)

target_sources(genyleap_sample_core
    PUBLIC
        FILE_SET CXX_MODULES
        FILES
            src/domain/app_domain.cppm
    PRIVATE
        src/domain/app_domain.cpp
)

set_property(
    TARGET genyleap_sample_core
    PROPERTY CXX_SCAN_FOR_MODULES ON
)

find_package(Qt6 6.12 REQUIRED COMPONENTS
    Quick
    Qml
    QuickControls2
)

if(QT_KNOWN_POLICY_QTP0004)
    qt_policy(SET QTP0004 NEW)
endif()

qt_standard_project_setup(REQUIRES 6.12)

qt_add_executable(GenyleapSample
    src/bootstrap/main.cpp
)

qt_add_qml_module(GenyleapSample
    URI Genyleap.Sample
    VERSION 1.0
    QML_FILES
        ui/Main.qml
)

target_link_libraries(GenyleapSample
    PRIVATE
        genyleap_sample_core
        Qt6::Quick
        Qt6::Qml
        Qt6::QuickControls2
)

target_compile_features(GenyleapSample
    PRIVATE
        cxx_std_26
)

C++src/bootstrap/main.cpp

#include <cstdlib>

#include <QCoreApplication>
#include <QGuiApplication>
#include <QQmlApplicationEngine>
#include <QObject>
#include <QQuickStyle>
#include <QString>

int main(int argc, char* argv[])
{
    QGuiApplication application {argc, argv};

    QQuickStyle::setStyle(QStringLiteral("Basic"));

    QQmlApplicationEngine engine;

    QObject::connect(
        &engine,
        &QQmlApplicationEngine::objectCreationFailed,
        &application,
        [] {
            QCoreApplication::exit(EXIT_FAILURE);
        },
        Qt::QueuedConnection
    );

    engine.loadFromModule("Genyleap.Sample", "Main");

    return application.exec();
}

Do not use experimental import std; as a reason to abandon modules.

프로젝트 소유 C++ modules가 계속 아키텍처의 중심입니다. standard-library headers는 standard-module path가 의도적이고 검증된 프로젝트 선택이 될 때까지 global module fragment에서 텍스트 방식으로 유지할 수 있습니다.

IDE

Install and configure Qt Creator.

The current stable Qt Creator release resolved from Qt's official latest index is 20.0.2. The official standalone package installs the IDE only; your self-built Qt SDKs stay where they are and are registered afterward as Qt versions and kits.

macOS · official universal package

ShellQt Creator 20.0.2

cd "$HOME/Downloads"
curl -fLO "https://download.qt.io/official_releases/qtcreator/latest/qt-creator-opensource-mac-universal-20.0.2_installer.dmg"
open "qt-creator-opensource-mac-universal-20.0.2_installer.dmg"

As a convenient package-manager alternative, brew install --cask qt-creator is available, but Qt does not officially support package-manager builds of Qt Creator.

Linux · official standalone installer

x86_64

ShellLinux x86_64

cd "$HOME/Downloads"
curl -fLO "https://download.qt.io/official_releases/qtcreator/latest/qt-creator-opensource-linux-x86_64-20.0.2.run"
chmod +x "qt-creator-opensource-linux-x86_64-20.0.2.run"
./"qt-creator-opensource-linux-x86_64-20.0.2.run"

arm64

ShellLinux arm64

cd "$HOME/Downloads"
curl -fLO "https://download.qt.io/official_releases/qtcreator/latest/qt-creator-opensource-linux-arm64-20.0.2.run"
chmod +x "qt-creator-opensource-linux-arm64-20.0.2.run"
./"qt-creator-opensource-linux-arm64-20.0.2.run"

Distribution packages can lag behind the current Qt Creator release, so use the official installer when the development stack is expected to track the current release.

Windows · official standalone installer

x86_64

PowerShellWindows x86_64

Set-Location "$HOME\Downloads"
Invoke-WebRequest -Uri "https://download.qt.io/official_releases/qtcreator/latest/qt-creator-opensource-windows-x86_64-20.0.2.exe" -OutFile "qt-creator-opensource-windows-x86_64-20.0.2.exe"

Start-Process -Wait ".\qt-creator-opensource-windows-x86_64-20.0.2.exe"

ARM64

PowerShellWindows ARM64

Set-Location "$HOME\Downloads"
Invoke-WebRequest -Uri "https://download.qt.io/official_releases/qtcreator/latest/qt-creator-opensource-windows-arm64-20.0.2.exe" -OutFile "qt-creator-opensource-windows-arm64-20.0.2.exe"

Start-Process -Wait ".\qt-creator-opensource-windows-arm64-20.0.2.exe"

choco install qtcreator is also available as a package-manager alternative on Windows, with the same caveat that package-manager distributions are not the officially supported delivery path.

Register the self-built Qt SDKs

먼저 CLI build를 증명하세요

Compiler, CMake, Ninja and the target's qt-cmake must work outside the IDE.

Add the Qt version

Open Preferences → Kits → Qt Versions → Add and select that Qt installation's bin/qtpaths or bin/qmake. For the desktop host, use $HOME/Qt/6.12.0/host/bin/qtpaths.

target마다 kit 하나를 만드세요

Keep Desktop, Android, iOS, iOS Simulator, WebAssembly and Remote Linux/embedded-device settings in separate kits.

Bind the toolchain

For each kit, select the matching compiler, CMake executable, Ninja generator, debugger, Qt version and run device. Do not let a host compiler leak into a cross-compiled target kit.

ShellVerify the host Qt before registering it

"$HOME/Qt/6.12.0/host/bin/qtpaths" --qt-version
"$HOME/Qt/6.12.0/host/bin/qtpaths" --install-prefix
"$HOME/Qt/6.12.0/host/bin/qt-cmake" --version

Raspberry Pi and other boards belong in a Remote Linux kit.

Add the board under Preferences → Devices, then create a kit that uses the matching cross compiler, self-built embedded Qt prefix and remote run device. Qt Creator can deploy and run the application over the configured device connection.

Qt WebEngine과 Qt PDF는 서로 독립적인 버전 민감성을 가집니다.

WebEngine/PDF 버전을 base Qt 버전에서 기계적으로 도출하지 마세요. release cadence가 다를 수 있습니다. 별도로 해석되는 dependency로 취급하고 source-build baseline에 넣기 전에 최신 release note를 검증하세요.

ready로 판단하기 전에 모든 target을 검증하세요.

ShellHost SDK

"$HOME/Qt/6.12.0/host/bin/qtpaths" --qt-version
"$HOME/Qt/6.12.0/host/bin/qtpaths" --install-prefix
"$HOME/Qt/6.12.0/host/bin/qt-cmake" --version

Then configure and build a real application with the target's own qt-cmake. For graphical applications, a core-library build is not sufficient evidence: generated MOC, QML type registration, resources, QML lint and a deterministic runtime smoke path all belong to final verification.

현재 upstream 레퍼런스.

Supported platformsCurrent desktop, mobile and WebAssembly compatibility matrix ↗ Build Qt for macOSCurrent Apple host and universal-build requirements ↗ Build Qt for LinuxCurrent x86_64 and arm64 desktop source-build guidance ↗ Cross-compile Qt for Linux devicesToolchain-file and sysroot model for ARM and other embedded targets ↗ Build Qt for AndroidCurrent host Qt, SDK, NDK and ABI guidance ↗ Android multi-ABI applicationsPackage multiple Qt ABI builds into APKs, AABs and AARs ↗ Build Qt for iOSCurrent device and simulator source-build guidance ↗ Qt for WebAssemblyCurrent Emscripten target and browser constraints ↗ Qt Creator latestCurrent stable Qt Creator download index ↗ Install Qt CreatorOfficial installation methods for macOS, Linux and Windows ↗ Register self-built Qt versionsAdd qmake or qtpaths and create matching kits ↗ Remote Linux devicesConfigure, deploy and run on Raspberry Pi and other Linux boards ↗ AI for Modern C++Modern module, CMake, Qt Quick and verification contract used by these examples ↗

Qt 개발.

hard-code된 가이드 버전이 아니라 현재 안정 릴리스를 따르세요.

source, build, install tree를 분리하세요.

현재 안정 source archive를 받으세요.

현재 target matrix.

먼저 host Qt를 build하세요.

macOS host

Linux host

Windows host

선택적 universal macOS SDK.

Linux architectures.

Native x86_64

Native arm64 / aarch64

Cross-compile x86_64 host → arm64 target

Cross-compile x86_64 host → ARMv7 hard-float

Raspberry Pi and other Linux boards.

Raspberry Pi 4 / 5 · 64-bit example

Deploy and verify on the board

Android.

macOS · arm64-v8a

Supported Android ABIs

macOS · armeabi-v7a

macOS · x86_64

If Gradle times out

Other host platforms

Multi-ABI application packages

iOS device and Simulator.

Default: build one Qt for iOS SDK containing device and Simulator libraries

Device-only SDK

Simulator-only SDK

Build an application

WebAssembly.

macOS / Linux: install and activate the matching Emscripten SDK

Repair an emsdk checkout that shows .emscripten: No such file or directory

Baseline single-threaded SDK

Threads + SIMD build

“전체 Qt”가 의미하는 것.

Modern Qt 프로젝트는 Modern C++ 프로젝트로 유지됩니다.

Install and configure Qt Creator.

macOS · official universal package

Linux · official standalone installer

x86_64

arm64

Windows · official standalone installer

x86_64

ARM64

Register the self-built Qt SDKs

먼저 CLI build를 증명하세요

Add the Qt version

target마다 kit 하나를 만드세요

Bind the toolchain

Qt WebEngine과 Qt PDF는 서로 독립적인 버전 민감성을 가집니다.

ready로 판단하기 전에 모든 target을 검증하세요.

현재 upstream 레퍼런스.

Repair an emsdk checkout that shows `.emscripten: No such file or directory`