組み込みLinuxデバイスの設定

特定のデバイス向けに Qt をクロスコンパイルするには、ツールチェーンと sysroot が必要です。ツールチェーンには、gcc または他のコンパイラ、およびクロスコンパイル用にビルドされた関連ツールが含まれていることが想定されます。 つまり、これらのツールはホストシステム（通常は x64）上で実行され、ターゲットアーキテクチャ（例えば、32 ビットまたは 64 ビットの ARM）向けのバイナリを生成します。sysroot にはターゲットシステム用のヘッダーとライブラリが含まれており、ホスト上でライブラリやアプリケーションのコンパイルおよびリンクが可能になります。

この概要ページでは、Yocto や Buildroot などのディストリビューション構築システムを使用しない、一般的なアプローチについて説明します。適切なツールチェーンと sysroot が利用可能であれば、いつでも Qt をクロスコンパイルしてデバイスに展開することが可能です。

X11 や Wayland などのウィンドウシステムを使用せずに Qt ベースのアプリケーションを実行する場合、一部のデバイスでは EGL および OpenGL ES をサポートするためにベンダー固有の適応コードが必要となります。これは、EGLFS プラットフォームプラグイン用のバックエンドの形で提供されています。 これは、ソフトウェアベースのレンダリングのみを目的としたLinuxFBプラットフォームプラグインを使用するプラットフォームなど、非アクセラレーション対応のプラットフォームには該当しません。Qt 6の時点で、多くの組み込みシステムでは、ビデオモードの設定、ディスプレイコネクタおよびグラフィカルサーフェスの管理にdrmを使用しています。 たとえば、NXP のi.MX8ベースのデバイスやRaspberry Pi 4はこのアプローチを採用しているため、EGLFSで最も一般的に使用されるバックエンドはeglfs_kmsです。これは、drm を使用したEGLおよびOpenGL ESベースのレンダリングを可能にし、サーフェスおよびバッファの管理にはgbm を使用します。NXP やi.MX6などの古いデバイスでは、EGLウィンドウサーフェスをフレームバッファに接続するために、GPUベンダー固有の従来のアプローチを引き続き使用し、eglfs_viv などの専用のeglfsバックエンドが使用されます。

組み込み Linux システムのグラフィックスおよび入力設定に関する詳細については、『Qt for Embedded Linux』を参照してください。

ツールチェーンファイルとデバイス・メイクスペック

Qt 5 では、通常、qtbase/mkspecs/devicesディレクトリにあるデバイス仕様を使用します。これらには、特定のデバイスに適したコンパイラおよびリンカのフラグが含まれており、sysroot 内の非標準の場所に EGL および OpenGL ES ライブラリが存在する場合でも、正しいライブラリが確実に選択されるようにします。

たとえば、Raspberry Pi 2 向けの Qt 5 ビルドは、次のような configure コマンドで設定できます。

./configure -release -opengl es2 -device linux-rasp-pi2-g++ -device-option CROSS_COMPILE=$TOOLCHAIN/arm-bcm2708/gcc-linaro-arm-linux-gnueabihf-raspbian/bin/arm-linux-gnueabihf- -sysroot $ROOTFS -prefix /usr/local/qt5

Qt 6 および CMake では、このアプローチだけでは不十分です。代わりに、configure を実行する前にCMake ツールチェーンファイルを指定する必要があります。コンパイラやリンカのフラグ、およびツールチェーンや sysroot 固有の特性に関するカスタマイズは、このファイル内で行われます。

以下のセクションでは、最小限のカスタマイズで多くのケースで使用できるツールチェーンファイルを紹介します。これは、このブログ記事で紹介されたアプローチに基づいています。

Qt自体のビルドにはCMakeのみがサポートされていますが、Qt 6.0ではqmake を使用してアプリケーションをビルドすることも可能です。クロスコンパイルで機能するqmake 環境を構築するには、CMakeまたはconfigureに対して、いくつかのレガシー引数を指定する必要があります。

ホストツール

Qtのクロスコンパイルには、Qtのホストビルドが利用可能である必要があります。詳細については、「Qtのクロスコンパイル」を参照してください。

Qt の設定

以下のものが利用可能であると仮定します：

• $HOME/rpi-sdk 配下のツールチェーンと sysroot、
• $HOME/qt-cross 配下に、少なくとも qtbase モジュールを含む Qt のチェックアウト、
• $HOME/qt-host ディレクトリ内のホスト用 Qt ビルド。

さらに、設定を行う前に以下の点を決定する必要があります：

• ビルド完了後、Qtのビルド結果をローカルシステムのどこにインストールするか？ この例では$HOME/qt6-rpi を使用します。
• デバイス上では、Qtのビルドをどこにデプロイしますか？この例では、/usr/local/qt6 を使用します。

この例では、Yocto を通じて生成された Raspberry Pi 4 SDK（ツールチェーン＋sysroot）を使用しますが、ここでの手順は完全に汎用的なものであり、Yocto に依存するものではありません。 ツールチェーンファイルに正しいクロスコンパイラやその他のパスが反映されていれば、他のツールチェーンやsysrootを使用する場合でも手順は同じです。

build ディレクトリを作成し、そこに移動した後：

$HOME/qt-cross/qtbase/configure -release -opengl es2 -nomake examples -nomake tests \
  -qt-host-path $HOME/qt-host                              \
  -extprefix $HOME/qt6-rpi                                 \
  -prefix /usr/local/qt6                                   \
  -- -DCMAKE_TOOLCHAIN_FILE=$HOME/qt-cross/toolchain.cmake

実際には、この configure コマンドは、以下の直接的な CMake 呼び出しと同等です：

cmake -GNinja -DCMAKE_BUILD_TYPE=Release -DINPUT_opengl=es2 -DQT_BUILD_EXAMPLES=OFF -DQT_BUILD_TESTS=OFF \
  -DQT_HOST_PATH=$HOME/qt-host                           \
  -DCMAKE_STAGING_PREFIX=$HOME/qt6-rpi                   \
  -DCMAKE_INSTALL_PREFIX=/usr/local/qt6                  \
  -DCMAKE_TOOLCHAIN_FILE=$HOME/qt-cross/toolchain.cmake  \
  $HOME/qt-cross/qtbase

適切なツールチェーンファイルがあれば、これでQtビルドを生成するのに十分であり、その後CMakeを使用してアプリケーションをビルドできるようになります。qmake でもアプリケーションをビルドできるようにするには、上記のすべての引数に加えて、Qt 5スタイルのデバイス仕様とデバイスオプションを指定する必要があります：

$HOME/qt-cross/qtbase/configure ...
  ...
  -device linux-rasp-pi4-v3d-g++ \
  -device-option CROSS_COMPILE=$HOME/rpi_sdk/sysroots/x86_64-pokysdk-linux/usr/bin/arm-poky-linux-gnueabi/arm-poky-linux-gnueabi- \
  -device-option DISTRO_OPTS="hard-float" \
  ...

デフォルトでは、クロスコンパイルを行う際、ターゲットデバイス上で実行される予定のQtライブラリとツールのみがビルドされます。moc やuic などのビルド関連ツールはビルドされません。これらのツールのビルドを有効にするには、QT_FORCE_BUILD_TOOLS をON に設定します。

設定がエラーなく完了したら、cmake --build . --parallel を実行してビルドを行います。ビルドが完了したら、cmake --install . を実行して結果を$HOME/qt6-rpi にインストールします。そこから、rsync、scp、またはその他の方法を使用して、Qtビルドをデバイスにデプロイできます。

個別の Qt モジュールをビルドする場合は、ステージング先のbin ディレクトリ（この例では$HOME/qt6-rpi ）にあるqt-configure-module スクリプトを使用して、qtdeclarative や qtquick3d などの追加モジュールを設定できます。その後、cmake --build . を使用してビルドし、以下のコマンドを実行してステージング先にインストールできます。cmake --install .

たとえば、OpenGL によるグラフィックスアクセラレーションを利用したい場合は、以下の機能に特に注意を払ってください：

EGL .................................... yes
OpenGL:
  Desktop OpenGL ....................... no
  OpenGL ES 2.0 ........................ yes
  OpenGL ES 3.0 ........................ yes
...
evdev .................................. yes
libinput ............................... yes
...
EGLFS .................................. yes
EGLFS details:
  EGLFS OpenWFD ........................ no
  EGLFS i.Mx6 .......................... no
  EGLFS i.Mx6 Wayland .................. no
  EGLFS RCAR ........................... no
  EGLFS EGLDevice ...................... yes
  EGLFS GBM ............................ yes
  EGLFS VSP2 ........................... no
  EGLFS Mali ........................... no
  EGLFS Raspberry Pi ................... no
  EGLFS X11 ............................ no
LinuxFB ................................ yes

Raspberry Pi 4の例では、EGL、OpenGL ES、およびEGLFS GBM がすべてyes として報告されることが期待されます。そうでない場合、EGLFSプラットフォームプラグインとそのeglfs_kmsバックエンドはデバイス上で機能しません。マウス、キーボード、タッチ入力を機能させるには、evdev またはlibinput のいずれかを有効にする必要があります。

同様に、デバイス上で X11 をウィンドウシステム（またはその一つ）として使用することを計画している場合は、xcb および X11 関連の機能がyes としてマークされていることを確認してください。

ツールチェーンファイルの例

$HOME/rpi-sdk 配下に sysroot とツールチェーンが存在することを前提とします。TARGET_SYSROOT およびCROSS_COMPILER は、使用中のツールチェーンと sysroot に合わせて調整する必要があります。ここでの例は、Yocto で生成された特定の SDK 1 つにのみ適しています。CMAKE_C_COMPILER およびCMAKE_CXX_COMPILER についても同様です。

PKG_CONFIG_* などの環境変数を設定するラッパースクリプトには依存していません。その代わりに、.pc ファイルへのパスはツールチェーンファイル内で指定されます。 別の sysroot を使用する場合は、PKG_CONFIG_LIBDIR での調整が必要になる可能性があります。例えば、Raspberry Pi OS（旧称 Raspbian）イメージから生成された sysroot を使用する場合は、代わりに/usr/lib/arm-gnueabihf/pkgconfig を使用します。

この例では、コンパイラおよびリンカのフラグは必ずしも最適とは限りません。ターゲットデバイスに合わせて必要に応じて調整してください。

この例示のツールチェーンファイルにおける CMake の詳細については、こちらのブログ記事およびCMake のドキュメントを参照してください。

cmake_minimum_required(VERSION 3.18)
include_guard(GLOBAL)

set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR arm)

set(TARGET_SYSROOT /home/user/rpi-sdk/sysroots/cortexa7t2hf-neon-vfpv4-poky-linux-gnueabi)
set(CROSS_COMPILER /home/user/rpi-sdk/sysroots/x86_64-pokysdk-linux/usr/bin/arm-poky-linux-gnueabi)

set(CMAKE_SYSROOT ${TARGET_SYSROOT})

set(ENV{PKG_CONFIG_PATH} "")
set(ENV{PKG_CONFIG_LIBDIR} ${CMAKE_SYSROOT}/usr/lib/pkgconfig:${CMAKE_SYSROOT}/usr/share/pkgconfig)
set(ENV{PKG_CONFIG_SYSROOT_DIR} ${CMAKE_SYSROOT})

set(CMAKE_C_COMPILER ${CROSS_COMPILER}/arm-poky-linux-gnueabi-gcc)
set(CMAKE_CXX_COMPILER ${CROSS_COMPILER}/arm-poky-linux-gnueabi-g++)

set(QT_COMPILER_FLAGS "-march=armv7-a -mfpu=neon -mfloat-abi=hard")
set(QT_COMPILER_FLAGS_RELEASE "-O2 -pipe")
set(QT_LINKER_FLAGS "-Wl,-O1 -Wl,--hash-style=gnu -Wl,--as-needed")

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)

include(CMakeInitializeConfigs)

function(cmake_initialize_per_config_variable _PREFIX _DOCSTRING)
  if (_PREFIX MATCHES "CMAKE_(C|CXX|ASM)_FLAGS")
    set(CMAKE_${CMAKE_MATCH_1}_FLAGS_INIT "${QT_COMPILER_FLAGS}")

    foreach (config DEBUG RELEASE MINSIZEREL RELWITHDEBINFO)
      if (DEFINED QT_COMPILER_FLAGS_${config})
        set(CMAKE_${CMAKE_MATCH_1}_FLAGS_${config}_INIT "${QT_COMPILER_FLAGS_${config}}")
      endif()
    endforeach()
  endif()

  if (_PREFIX MATCHES "CMAKE_(SHARED|MODULE|EXE)_LINKER_FLAGS")
    foreach (config SHARED MODULE EXE)
      set(CMAKE_${config}_LINKER_FLAGS_INIT "${QT_LINKER_FLAGS}")
    endforeach()
  endif()

  _cmake_initialize_per_config_variable(${ARGV})
endfunction()

ターゲットデバイス向けアプリケーションのビルド

Qtのビルドが完了し、ステージング場所にインストールされたら、サンプルやアプリケーションをビルドできます。

CMake を使用する場合は、ステージング先のbin ディレクトリ（この例では$HOME/qt6-rpi ）にある生成されたqt-cmake スクリプトを使用して設定を行い、その後ninja を実行します。例：

$HOME/qt6-rpi/bin/qt-cmake .
cmake --build .

生成されたアプリケーションバイナリは、その後デバイスにデプロイできます。qt-cmake ヘルパースクリプトを使用すると便利です。このスクリプトは、Qtのビルドに使用されたツールチェーンファイルが確実に読み込まれるようにするため、アプリケーションごとにそれを繰り返し指定する必要がありません。

Qt 自体とは異なり、Qt 6.0 では、適切なデバイス仕様が利用可能であり、かつ Qt の設定時に CMake または configure に適切なレガシー引数が渡されている限り、qmake によるアプリケーションのビルドは引き続きサポートされています。これらの条件がすべて満たされている場合、qmake およびmake を実行することで、ターゲットデバイス用のアプリケーションバイナリも生成されます。

プラットフォームプラグインおよびEGLFSのデフォルト設定

設定が完了すると、デフォルトのプラットフォームプラグインが選択されます。これは、-platform 引数を指定せず、かつQT_QPA_PLATFORM 環境変数が設定されていない状態でアプリケーションを起動する際に使用されます。

同様に、EGLFSプラットフォームプラグインにも複数のバックエンドがあります。デフォルトは、利用可能性と事前に定義された優先順位に基づいて選択されます。drmおよびgbmが利用可能な場合、デフォルトはeglfs_kmsバックエンドになります。これは、実行時にQT_QPA_EGLFS_INTEGRATION 環境変数を設定することで、いつでも上書き可能です。

実行時に特定の値を強制することなく、ビルド時のこれらのデフォルト設定を変更するには、CMake を一度実行した後、次の 2 つの CMake キャッシュ変数を利用できます:

• QT_QPA_DEFAULT_PLATFORM (STRING) - デフォルトのプラットフォームプラグイン名。
• QT_QPA_DEFAULT_EGLFS_INTEGRATION (STRING) - デフォルトの EGLFS バックエンド。

これらの変数は、ツールチェーンファイル内でも設定できます。

Qt の設定に関する詳細については、「Qt の設定オプション」を参照してください。