Qt for Linux - デプロイメント

このドキュメントでは、Qt for Linux のデプロイに関する具体的な問題について説明します。ここでは、Qt ソースパッケージに付属しているPlug & Paintサンプルアプリケーションのデプロイについて説明します。

Unix システム（商用 Unix や Linux ディストリビューションなど）の普及により、Unix でのデプロイは複雑なトピックになっています。始める前に、あるUnixフレーバー用にコンパイルされたプログラムは、おそらく異なるUnixシステムでは動作しないことに注意してください。例えば、クロスコンパイラを使わない限り、IrixでコンパイルしたアプリケーションをAIXで配布することはできません。

共有ライブラリ

共有ライブラリを使ってplugandpaint アプリケーションを配布する場合、2 つの課題があります：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 ライブラリをシステム・ライブラリ・パスの 1 つにインストールすることができます（たいていのシス テムでは、/usr/lib ）。
• アプリケーションをリンクする際に、-rpath コマンドラインオプションに所定のパスを渡すことができます。これにより、アプリケーションを起動するときに、ダイナミック・リンカーにこのディレクトリを探すように指示します。
• アプリケーションのスタートアップ・スクリプトを作成し、ダイナミック・リンカ の設定を変更することができます（例えば、アプリケーションのディレクトリをLD_LIBRARY_PATH 環境変数に追加します）。

  注意: アプリケーションを "実行時にユーザーIDを設定する "設定にして実行し、そのオーナーをrootにする場合、一部のプラットフォームではLD_LIBRARY_PATHが無視されます。この場合、LD_LIBRARY_PATHを使用することはできません）。

最初の方法の欠点は、ユーザーがスーパー・ユーザー権限を持っていなければならないことである。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

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

ほとんどのシステムでは、共有ライブラリの拡張子は.so です。特筆すべき例外は HP-UX で、.sl を使用しています。

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

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

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

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

静的リンク

静的リンクは、Qt ライブラリを配布する作業から解放され、Qt ライブラリがターゲットシステムのデフォルトの検索パスにあることを確認できるため、Unix 上でアプリケーションを配布する最も安全で簡単な方法です。

Qt を静的にビルドする

この方法を使うには、Qt ライブラリの静的バージョンのビルドから始めなければなりません。Qt for Linux - Building from Source の手順に従ってください。ただし、configure に-static という引数を追加することを忘れないでください：

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

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

Qt を静的にビルドしたら、次は makefile を再生成してアプリケーションを再構築します。まず、アプリケーションのあるディレクトリに入ります：

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

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

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

おそらくリリース・ライブラリーに対してリンクしたいでしょうから、qmake を起動するときにこれを指定してください。おそらく、リリース・ライブラリに対してリンクしたいでしょうから、 を呼び出すときにこれを指定することができます。

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

ldd ./application

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

さて、すべてがエラーなくコンパイルされリンクされていれば、plugandpaint ファイルができあがり、デプロイする準備ができました。アプリケーションが本当にスタンドアロンで実行できるかどうかを確認する簡単な方法の1つは、QtやQtアプリケーションがインストールされていないマシンにアプリケーションをコピーし、そのマシンで実行することです。

アプリケーションがコンパイラ固有のライブラリに依存している場合、これらのライブラリもアプリケーションと一緒に再配布する必要があることを覚えておいてください。詳しくは、アプリケーションの依存関係を参照してください。

Plug & Paint のサンプルはいくつかのコンポーネントで構成されています：コアアプリケーション（Plug & Paint）、Basic ToolsとExtra Filtersプラグインです。プラグインはスタティックリンクアプローチではデプロイできないため、これまで用意した実行ファイルは不完全なものです。アプリケーションは実行されますが、プラグインが欠けているため、機能は無効になります。プラグイン・ベースのアプリケーションをデプロイするには、共有ライブラリ・アプローチを使うべきです。

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

追加ライブラリ

アプリケーションが依存しているライブラリを調べるには、ldd （ほとんどのUnixで利用可能）ツールを実行してください：

ldd ./application

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

実装によっては、他の共有ライブラリをdlopen() で開こうとするものがあり、これに失敗すると、X11ライブラリが原因でアプリケーションがクラッシュする可能性があるからです。

また、QtはXineramaやXrandrのような特定のX11拡張を探し、リンクするすべてのライブラリを含め、それらを取り込む可能性があることも触れておく価値があります。特定の拡張機能が存在することを保証できない場合、最も安全な方法は、Qt を設定する際にその拡張機能を無効にすることです (例えば、./configure -no-xrandr)。

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

静的 Qt ライブラリに対してアプリケーションをリンクする場合、上記の依存ライブラリを明示的にリンクする必要があります。プロジェクトファイルのLIBS 変数に追加してください。

Qt プラグイン

すべてのQt GUI アプリケーションには、Qt のQPA（Qt Platform Abstraction）レイヤーを実装するプラグインが必要です。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 Plugins の作成方法」ドキュメントでは、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