Linux 向け Qt - 導入

このドキュメントでは、Linux 向け Qt に関する具体的な導入上の問題について解説します。ここでは、Qt ソースパッケージに同梱されているサンプルアプリケーション「Plug & Paint」を導入する手順を例に説明します。

商用UnixやLinuxディストリビューションなど、Unix系システムが多数存在するため、Unix上でのデプロイは複雑なトピックとなります。 始める前に、ある種類の Unix 向けにコンパイルされたプログラムは、別の Unix システムでは実行できない可能性が高いことに留意してください。たとえば、クロスコンパイラを使用しない限り、Irix でアプリケーションをコンパイルして AIX で配布することはできません。

共有ライブラリ

共有ライブラリアプローチを使用してplugandpaint アプリケーションをデプロイする場合、2つの課題があります。1つは、アプリケーションの実行ファイルとともにQtランタイムを正しく再配布する必要があること、もう1つは、アプリケーションがプラグインを認識できるように、ターゲットシステム上の適切な場所にプラグインをインストールする必要があることです。

Qtを共有ライブラリとしてビルドする

ここでは、Qt を共有ライブラリとして（Qt インストール時のデフォルト設定通り）/path/to/Qt ディレクトリにすでにインストール済みであることを前提としています。

アプリケーションを共有ライブラリとしての Qt にリンクする

Qtが共有ライブラリとしてビルドされていることを確認した後、plugandpaint アプリケーションをビルドできます。まず、アプリケーションが含まれているディレクトリに移動する必要があります：

cd /path/to/Qt/examples/tools/plugandpaint

次に、qmake を実行してアプリケーション用の新しい makefile を作成し、クリーンビルドを行って動的リンクされた実行ファイルを作成します：

make clean
qmake -config release
make

これでコアアプリケーションがビルドされます。次に、以下のコマンドでプラグインをビルドします：

cd ../plugandpaint/plugins
make clean
qmake -config release
make

エラーなくコンパイルおよびリンクが完了すれば、plugandpaint 実行ファイルと、libpnp_basictools.so およびlibpnp_extrafilters.so プラグインファイルが生成されます。

アプリケーションパッケージの作成

Unix には標準的なパッケージ管理システムが存在しないため、以下に示す方法は汎用的な解決策となります。パッケージの作成方法については、対象システムのドキュメントを参照してください。

アプリケーションをデプロイするには、関連する Qt ライブラリ（アプリケーションで使用されている Qt モジュールに対応するもの）、プラットフォームプラグイン、および実行ファイルを同じディレクトリツリーにコピーする必要があります。 アプリケーションがコンパイラ固有のライブラリに依存している場合は、これらもアプリケーションと共に再配布する必要があることに注意してください。詳細については、「アプリケーションの依存関係」のセクションを参照してください。

プラグインについては後ほど説明しますが、共有ライブラリに関する主な課題は、動的リンカーが Qt ライブラリを確実に検出できるようにする必要があるという点です。特に指定がない限り、動的リンカーはアプリケーションが配置されているディレクトリを検索しません。この問題を解決する方法はいくつかあります：

• Qtライブラリをシステムのライブラリパス（多くのシステムでは、例えば/usr/lib ）のいずれかにインストールします。
• アプリケーションをリンクする際、-rpath コマンドラインオプションに所定のパスを指定することができます。これにより、アプリケーションの起動時にダイナミックリンカーがこのディレクトリを検索するようになります。
• アプリケーション用の起動スクリプトを作成し、そこで動的リンカーの設定を変更します（例：LD_LIBRARY_PATH 環境変数にアプリケーションのディレクトリを追加するなど）。

  注: アプリケーションが「実行時にユーザー ID を設定」して実行され、かつ所有者が root である場合、一部のプラットフォームでは LD_LIBRARY_PATH は無視されます。この場合、LD_LIBRARY_PATH を使用する方法は選択肢にはなりません。

1つ目の方法の欠点は、ユーザーにスーパーユーザー権限が必要なことです。2つ目の方法の欠点は、ユーザーが所定のパスにインストールする権限を持っていない可能性があることです。いずれの場合も、ユーザーはホームディレクトリにインストールする選択肢がありません。 最も柔軟性が高いため、3番目のアプローチの使用を推奨します。例えば、plugandpaint.sh スクリプトは次のようになります：

#!/bin/sh
appname=`basename $0 | sed s,\.sh$,,`

dirname=`dirname $0`
tmp="${dirname#?}"

if [ "${dirname%$tmp}" != "/" ]; then
dirname=$PWD/$dirname
fi
LD_LIBRARY_PATH=$dirname
export LD_LIBRARY_PATH
$dirname/$appname "$@"

実行ファイルの代わりにこのスクリプトを実行することで、動的リンカーが Qt ライブラリを確実に検出できるようになります。なお、他のアプリケーションで使用する場合も、スクリプトの名前を変更するだけで済みます。

プラグインを検索する際、アプリケーションは実行ファイルのディレクトリ内にある「plugins」サブディレクトリを検索します。プラグインをplugins ディレクトリに手動でコピーするか、プラグインのプロジェクトファイルでDESTDIR を設定する必要があります：

DESTDIR = /path/to/Qt/plugandpaint/plugins

plugandpaint アプリケーションの実行に必要なすべてのQtライブラリおよびプラグインを配布するアーカイブには、以下のファイルを含める必要があります：

ほとんどのシステムでは、共有ライブラリの拡張子は `.so` です。注目すべき例外として、HP-UX では `.sl` が使用されます。

アプリケーションがコンパイラ固有のライブラリに依存している場合、それらもアプリケーションとともに再配布する必要があることに注意してください。詳細については、「アプリケーションの依存関係」のセクションを参照してください。

アプリケーションが正常にデプロイできることを確認するには、Qt もコンパイラもインストールされていないマシンにこのアーカイブを解凍し、実行（つまり、plugandpaint.sh スクリプトを実行）してみてください。

プラグインをplugins サブディレクトリに配置する代わりに、QApplication::addLibraryPath() またはQApplication::setLibraryPaths() を使用してアプリケーションを起動する際に、カスタム検索パスを追加することもできます。

QCoreApplication::addLibraryPath("/some/other/path");

静的リンク

静的リンクは、Unix 上でアプリケーションを配布する上で、多くの場合、最も安全かつ簡単な方法です。これは、Qt ライブラリを配布したり、ターゲットシステムのライブラリのデフォルトの検索パスにライブラリが確実に配置されていることを確認したりする手間が省けるためです。

Qt の静的リンク

この手法を使用するには、まず Qt ライブラリの _静的_ バージョンをビルドする必要があります。「Qt for Linux - ソースからのビルド」の手順に従ってください。ただし、configure に-static 引数を追加することを忘れないでください:

mkdir -p ~/dev/qt-build
cd ~/dev/qt-build
/tmp/qt-everywhere-src-6.12.0/configure -static

アプリケーションを静的リンク版Qtにリンクする

Qtの静的リンク版がビルドされたら、次のステップとしてmakefileを再生成し、アプリケーションを再ビルドします。まず、アプリケーションが含まれているディレクトリに移動する必要があります：

cd /path/to/Qt/examples/widgets/tools/plugandpaint/app

次に、qmake を実行してアプリケーション用の新しい makefile を作成し、clean ビルドを行って静的リンクされた実行ファイルを作成します:

make clean
PATH=/path/to/Qt/bin:$PATH
export PATH
qmake -config release
make

おそらくリリース版ライブラリに対してリンクしたいでしょう。これは `qmake` を実行する際に指定できます。なお、先ほどビルドした静的Qtへのパスを設定する必要がある点に注意してください。

アプリケーションが実際にQtと静的にリンクされていることを確認するには、ldd ツール（ほとんどのUnix系OSで利用可能）を実行します：

ldd ./application

出力に Qt ライブラリが記載されていないことを確認してください。

これで、コンパイルとリンクがエラーなく完了していれば、デプロイ可能なplugandpaint ファイルが作成されているはずです。アプリケーションが実際にスタンドアロンで実行できるかどうかを確認する簡単な方法として、Qt や Qt アプリケーションがインストールされていないマシンにアプリケーションをコピーし、そのマシン上で実行してみてください。

アプリケーションがコンパイラ固有のライブラリに依存している場合は、それらもアプリケーションと共に再配布する必要があることに注意してください。詳細については、「アプリケーションの依存関係」のセクションを参照してください。

「Plug & Paint」のサンプルは、コアアプリケーション（Plug & Paint）と、「Basic Tools」および「Extra Filters」プラグインという、いくつかのコンポーネントで構成されています。静的リンク方式ではプラグインをデプロイできないため、ここまでで準備した実行ファイルは不完全な状態です。 アプリケーションは実行されますが、プラグインが欠落しているため機能は使用できません。プラグインベースのアプリケーションを展開するには、共有ライブラリ方式を使用する必要があります。

アプリケーションの依存関係

追加のライブラリ

アプリケーションがどのライブラリに依存しているかを確認するには、ldd ツール（ほとんどのUnix系OSで利用可能）を実行します:

ldd ./application

これにより、アプリケーションのすべての共有ライブラリ依存関係が一覧表示されます。 設定によっては、これらのライブラリをアプリケーションと一緒に再配布する必要があります。特に、システムのコンパイラとバイナリ互換性のないコンパイラでアプリケーションをコンパイルする場合は、標準 C++ ライブラリを再配布する必要があります。可能であれば、これらのライブラリに対して静的にリンクするのが最も安全な解決策です。

通常の X11 ライブラリについては、動的にリンクすることをお勧めします。これは、一部の実装では `dlopen()` を使用して他の共有ライブラリを開こうとし、これが失敗した場合、X11 ライブラリが原因でアプリケーションがクラッシュする可能性があるためです。

また、QtはXineramaやXrandrなどの特定のX11拡張機能を検索し、それらにリンクされているすべてのライブラリを含めて取り込む可能性がある点にも言及しておく価値があります。特定の拡張機能の存在を保証できない場合は、Qtの構成時にそれを無効にするのが最も安全なアプローチです（例：./configure -no-xrandr ）。

FontConfig や FreeType も、常に利用可能とは限らない、あるいはバイナリ互換性が常に保たれているとは限らないライブラリの例です。奇妙に聞こえるかもしれませんが、一部のソフトウェアベンダーは、非常に古いマシン上でソフトウェアをコンパイルし、そのマシン上で動作するソフトウェアを一切アップグレードしないよう細心の注意を払うことで、成功を収めています。

アプリケーションを静的 Qt ライブラリに対してリンクする際は、前述の依存ライブラリを明示的にリンクする必要があります。これを行うには、プロジェクトファイル内のLIBS 変数にそれらを追加してください。

Qtプラグイン

すべてのQt GUI アプリケーションには、QtのQt Platform Abstraction(QPA) レイヤを実装するプラグインが必要です。Linux/X11の場合、プラットフォームプラグインの名前はlibqxcb.so です。このファイルは、ディストリビューションディレクトリ内の特定のサブディレクトリ（デフォルトではplatforms ）に配置する必要があります。 あるいは、以下で説明するように、Qtがプラグインを検索するために使用する検索パスを調整することも可能です。

また、アプリケーションは、JPEG 画像フォーマットプラグインや SQL ドライバプラグインなど、1 つ以上の Qt プラグインに依存している場合があります。必要な Qt プラグインは、必ずアプリケーションと一緒に配布してください。プラットフォームプラグインと同様に、各種類のプラグインは、配布ディレクトリ内の特定のサブディレクトリ（imageformats やsqldrivers など）に配置する必要があります。

Qt プラグインの検索パス（およびその他のいくつかのパス）は、QtCore ライブラリにハードコードされています。デフォルトでは、最初のプラグイン検索パスは/path/to/Qt/plugins としてハードコードされます。前述のように、あらかじめ決められたパスを使用することにはいくつかの欠点があるため、Qt プラグインが確実に検出されるよう、さまざまな代替案を検討する必要があります。

• qt.conf を使用する。これは最も柔軟性が高いため、推奨されるアプローチです。
• QApplication::addLibraryPath() またはQApplication::setLibraryPaths() を使用する。
• サードパーティ製のインストールユーティリティ、またはターゲットシステムのパッケージマネージャーを使用して、QtCore ライブラリ内のハードコーディングされたパスを変更する。

「Qt プラグインの作成方法」というドキュメントでは、Qt アプリケーション用のプラグインをビルドおよび展開する際に注意すべき事項について概説しています。

チュートリアル：DEB パッケージの作成

このセクションでは、Qt 6.5 以降で利用可能な CMake デプロイメント API を使用して、Linux 上の Qt アプリケーション用の DEB パッケージを作成する方法について説明します。専用のlinuxdeployqt ツールは存在しません。現在のソリューションは、CMake の組み込み機能のみに依存しています。

サンプルプロジェクトの設定

まずは、シンプルな CMake プロジェクトから始めましょう：

cmake_minimum_required(VERSION 3.22)
project(MyApp)

find_package(Qt6 REQUIRED COMPONENTS Widgets)
qt_standard_project_setup()

qt_add_executable(MyApp main.cpp)
target_link_libraries(MyApp PRIVATE Qt::Widgets)

ステップ1：インストール環境の準備

アプリケーションをインストールし、自己完結型のディレクトリを作成するためのデプロイメントスクリプトを生成するコマンドを追加します：

# Install the executable to "${CMAKE_INSTALL_PREFIX}/bin".
install(TARGETS MyApp
    BUNDLE  DESTINATION .
    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
)

# Generate the deployment script for MyApp.
qt_generate_deploy_app_script(
    TARGET MyApp
    FILENAME_VARIABLE deploy_script
    NO_UNSUPPORTED_PLATFORM_ERROR
)

# Run the deployment script during installation (on "cmake --install").
install(SCRIPT ${deploy_script})

プロジェクトをビルドしてインストールします：

qt-cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/tmp/my-application ..
cmake --build .
cmake --install .

デプロイメントスクリプト：

• 実行ファイルの隣に、ディレクトリ構成に関する情報が含まれた `qt.conf` ファイルを作成します。これは、実行時にプラグインやアセットを見つけるために必要です。詳細については、qt.conf のドキュメントを参照してください。
• CMakeに組み込まれている関数（GET_RUNTIME_DEPENDENCIES）を使用して、実行ファイルおよび使用されているQtプラグインを解析し、デプロイすべきQtライブラリを特定します。
• 必要な Qt プラグインと Qt ライブラリをインストールします。

これで、インストールディレクトリを別のマシンにコピーしても、アプリケーションは正常に動作するはずです。

ステップ 2: DEB パッケージの作成

インストール後、CPack を使用してディレクトリをパッケージ化します。CMake プロジェクトに以下を追加してください：

set(CPACK_PACKAGE_NAME my-app)
set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "My amazing application")
set(CPACK_PACKAGE_VENDOR "My Company")
set(CPACK_PACKAGE_INSTALL_DIRECTORY ${CPACK_PACKAGE_NAME})
set(CPACK_VERBATIM_VARIABLES ON)
set(CPACK_PACKAGING_INSTALL_PREFIX "/opt/myapp")
set(CPACK_DEBIAN_PACKAGE_MAINTAINER "Package Maintainer <maintainer@example.com>")
set(CPACK_DEBIAN_PACKAGE_DEPENDS libc6 libstdc++6 libgcc-s1)
include(CPack)

プロジェクトを再構成し、ビルドディレクトリ（CPackConfig.cmake ファイルが含まれている必要があります）に移動して、CPackを実行し、DEBパッケージを生成します：

cpack -G DEB

パッケージの内容を確認するには：

dpkg -c my_app-1.0-Linux.deb

パッケージをインストールするには：

sudo dpkg -i my_app-1.0-Linux.deb