Building QtWebEngine/QtPdf for Windows ARM64

This guide provides comprehensive instructions for building QtWebEngine and QtPdf for Windows ARM64 architecture. As of the current Qt releases, official ARM64 binaries for QtWebEngine are not available, making this build process necessary for ARM64 development.

Prerequisites

System Requirements

• Windows 10/11 x64 system for cross-compilation
• Visual Studio 2022 with MSVC toolchain
• At least 16GB RAM (32GB recommended)
• 50GB+ free disk space
• Git for version control

Required Visual Studio Components

Ensure you have the following Visual Studio 2022 components installed:

• MSVC v143 - VS 2022 C++ x64/x86 build tools
• MSVC v143 - VS 2022 C++ ARM64 build tools
• Windows 11 SDK (latest version)
• CMake tools for Visual Studio
• Git for Windows
• MSVC v143 - VS 2022 C++ ATL for latest v143 build tools (x86 & x64)
• MSVC v143 - VS 2022 C++ ATL for latest v143 build tools (ARM64)

Step 1: Install Qt 6 for x64 (Host) and ARM64 (Target)

Option 1: Using aqt (Recommended)

First, install the Python package manager and aqt:

pip install aqtinstall

Install Qt 6 for Windows x64 (host compiler):

aqt install-qt --outputdir C:\Qt windows desktop 6.9.0 win64_msvc2022_64

Install Qt 6 for Windows ARM64 (target compiler):

aqt install-qt --outputdir C:\Qt windows desktop 6.9.0 win64_msvc2022_arm64

Option 2: Qt Online Installer

1. Download the Qt Online Installer from qt.io
2. Install Qt 6.9.0 with the following components:
   • MSVC 2022 64-bit (host)
   • MSVC 2022 ARM64 (target)

Step 2: Clone and Prepare QtWebEngine Source

Open x64 Native Tools Command Prompt for VS 2022 and execute:

# Navigate to your desired build location
cd C:\

# Clone the QtWebEngine repository
git clone https://code.qt.io/qt/qtwebengine.git
cd qtwebengine

# Checkout the desired version (match your Qt version)
git checkout 6.9.0

# Initialize and update all submodules (this will take time)
git submodule update --init --recursive

# Return to the root directory
cd ..

Step 3: Apply Required Patches

Before building, you need to apply a critical patch to fix compilation issues with the V8 engine on ARM64.

Apply the V8 Patch

Apply a patch file to fix the marking state issue:

# Navigate to the qtwebengine chromium directory
cd C:\qtwebengine\src\3rdparty\chromium

# Create the patch file
curl -LO https://raw.githubusercontent.com/fauzanelka/qtwebengine-arm64/refs/heads/main/v8-marking-state.patch

# Apply the patch
git apply v8-marking-state.patch

Alternative: Manual File Edit

If the patch command fails, you can manually edit the file:

1. Open C:\qtwebengine\chromium\v8\src\heap\cppgc\marking-state.h in a text editor
2. Find line ~361 that contains:

   return MutatorMarkingState::BasicMarkingState::MarkNoPush(header);

3. Replace it with:

   return BasicMarkingState::MarkNoPush(header);

4. Save the file

Important: This patch fixes a C++ compilation error where the qualified name lookup fails on ARM64 builds. Without this patch, the build will fail with compilation errors.

Step 4: Build GN (Google's Build System) for Cross-Compilation

GN must be built first as a native x64 binary before cross-compiling QtWebEngine.

# Create build directory
mkdir build-qtwebengine-arm64
cd build-qtwebengine-arm64

# Configure to build only GN initially
C:\Qt\6.9.0\msvc2022_64\bin\qt-configure-module.bat ..\qtwebengine -- -DBUILD_ONLY_GN=ON

# Build GN (may fail on first attempt - this is normal)
cmake --build . --parallel

# Build again (should succeed on second attempt)
cmake --build . --parallel

Note: The GN build often fails on the first attempt due to dependency resolution. Running the build command twice typically resolves this issue.

Step 5: Cross-Compile QtWebEngine/QtPdf for ARM64

Open Cross-Compilation Environment

You need to switch to the ARM64 cross-compilation environment. Do one of the following:

Option A: Run the batch file directly:

"C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvarsamd64_arm64.bat"

Option B: Open "x64_arm64 Cross Tools Command Prompt for VS 2022" from the Start Menu

Configure and Build

Navigate back to your build directory and configure for ARM64:

cd C:\build-qtwebengine-arm64

# Clear CMakeCache.txt
rm CMakeCache.txt

# Configure for ARM64 cross-compilation
C:\Qt\6.9.0\msvc2022_arm64\bin\qt-configure-module.bat ..\qtwebengine -- -DQT_HOST_PATH=C:\Qt\6.9.0\msvc2022_64 -DFEATURE_webengine_build=OFF

Build Options

Choose one of the following based on your needs:

To build only QtPdf (faster, recommended for most users):

C:\Qt\6.9.0\msvc2022_arm64\bin\qt-configure-module.bat ..\qtwebengine -- -DQT_HOST_PATH=C:\Qt\6.9.0\msvc2022_64 -DFEATURE_webengine_build=OFF

To build both QtPdf and QtWebEngine (slower, complete build):

C:\Qt\6.9.0\msvc2022_arm64\bin\qt-configure-module.bat ..\qtwebengine -- -DQT_HOST_PATH=C:\Qt\6.9.0\msvc2022_64 -DFEATURE_webengine_build=ON

Start the Build Process

# Begin the build (this will take several hours)
cmake --build . --parallel

Step 6: Install QtWebEngine/QtPdf

After the build is complete, you need to install the libraries. It's recommended to install to a separate directory to avoid conflicts with your native Qt installation.

Install to a Custom Directory (Recommended)

# Install to a separate ARM64-specific directory
cmake --install . --prefix C:\Qt-arm64

# Alternative: Install to a versioned directory
cmake --install . --prefix C:\Qt\6.9.0-arm64

Create a Redistributable Archive

After installation, you can create a ZIP archive for easy distribution:

# Navigate to the installation directory
cd C:\Qt-arm64

# Create a ZIP archive (requires 7-zip or similar)
# Using PowerShell:
Compress-Archive -Path ".\*" -DestinationPath "C:\QtWebEngine-6.9.0-ARM64.zip"

# Or using 7-zip (if installed):
7z a "C:\QtWebEngine-6.9.0-ARM64.zip" "C:\Qt-arm64\*"

Build Time Expectations

• QtPdf only: 30-60 minutes (depending on hardware)
• QtPdf + QtWebEngine: 2-6 hours (depending on hardware)

Troubleshooting

Common Issues

1. GN Build Fails

   • Solution: Run the build command twice as shown in Step 3

2. Out of Memory Errors

   • Reduce parallel jobs: cmake --build . --parallel 4
   • Ensure you have adequate RAM and virtual memory

3. Missing Dependencies

   • Verify all Visual Studio components are installed
   • Check that both x64 and ARM64 MSVC toolchains are available

4. Git Submodule Issues

   • Run: git submodule update --init --recursive --force

5. V8 Compilation Errors

   • Ensure the V8 patch from Step 3 has been applied correctly
   • Check that the file chromium/v8/src/heap/cppgc/marking-state.h contains the corrected line
   • If you see errors related to MutatorMarkingState::BasicMarkingState, the patch wasn't applied

Verification

After a successful build and installation, you should find the ARM64 libraries in:

• C:\Qt-arm64\lib\ (if using custom installation directory)
• C:\Qt\6.9.0\msvc2022_arm64\lib\ (if installed to existing Qt directory)
• Or in your build directory under appropriate subdirectories (before installation)

Key files to look for:

• Qt6WebEngine.dll and Qt6WebEngine.lib (if building full QtWebEngine)
• Qt6Pdf.dll and Qt6Pdf.lib (QtPdf libraries)
• Qt6WebEngineCore.dll (core WebEngine components)

Usage

Once built and installed, you can use QtWebEngine/QtPdf in your ARM64 applications by:

1. Setting your Qt installation path: Point your development environment to the ARM64 installation directory (e.g., C:\Qt-arm64)
2. Configuring your project: Set your project to target ARM64 architecture
3. Linking against the libraries: Link against the newly built QtWebEngine/QtPdf libraries
4. Deploying: Include the ARM64 DLLs with your application distribution

Using the Custom Installation

If you installed to C:\Qt-arm64, you can:

• Set CMAKE_PREFIX_PATH to C:\Qt-arm64 in your CMake projects
• Or set QTDIR environment variable to C:\Qt-arm64
• Add C:\Qt-arm64\bin to your PATH for runtime DLL discovery

Additional Notes

• This process requires significant disk space and time
• Building on a machine with SSD storage will significantly improve build times
• Consider using a dedicated build machine or VM with ample resources
• Keep your Qt version, Visual Studio, and Windows SDK up to date for best compatibility

Contributing

If you encounter issues or have improvements to this guide, please feel free to submit issues or pull requests.