Android のシンボル
アプリケーションのデバッグを支援するために、Unity のネイティブライブラリのシンボルファイルを含むパッケージを生成することができます。シンボルファイルには、アクティブなメモリアドレスをメソッド名などの使用可能な情報に変換するテーブルが含まれています。この変換プロセスをシンボル化と呼びます。シンボルパッケージを Google Play Console にアップロードすると、Android Vitals ダッシュボードで人間が読めるスタックトレースを表示できます。
シンボルファイルには 2 種類あります。
- パブリック: シンボルテーブルを含む小さなファイルです。詳細は、パブリックシンボル を参照してください。
- デバッグ: パブリックシンボルファイルに含まれるすべての情報と、より詳細なデバッグに使用できる完全なデバッグ情報が含まれています。詳しくは、デバッグシンボル を参照してください。
以下のライブラリのシンボルファイルを生成することができます。
-
libmain: 最初の Unity エンジンのロードロジック関連。 -
libunity: Unity のエンジンコード。 -
libil2cpp: C++ コードに変換したプロジェクトからの C# スクリプトを含みます。
Unity は、libmain と libunity のシンボルファイルを生成します。Gradle は、libil2cpp のシンボルファイルを生成します。
パブリックシンボル
パブリックシンボルファイルには、関数のアドレスを人間が読める文字列に解決する情報が含まれています。Unity は --strip-debug パラメーターを使用して、詳細なデバッグ情報を削除したパブリックシンボルを作成します。これにより、パブリックシンボルファイルとパッケージは、デバッグシンボル ファイルとパッケージよりも小さくなります。
デバッグシンボル
デバッグシンボルファイルには、完全なデバッグ情報とシンボルテーブルが含まれています。それを使って以下を行えます。
- スタックトレースを解決し、ソースコードが利用可能なアプリケーションをデバッグすることができます。
- アプリケーションにネイティブデバッガーを取り付け、コードをデバッグします。
Unity は、--only-keep-debug パラメーターを使用して、デバッグシンボルを作成します。詳細については、Linux ユーザーマニュアルの–only-keep-debug を参照してください。
ノート: デバッグシンボルが利用できない場合、Unity はビルド時に パブリックシンボル ファイルをプロジェクトに配置します。libmain と libunity のライブラリではデバッグシンボルは利用できないため、Unity は常にパブリックシンボルファイルを生成します。
カスタムシンボル
追加のシンボルファイルを加えるように Unity に指示できます。これは、アプリケーションがクラッシュした場合に、共有ライブラリを使用し、ローカルデバッガや Google Play で共有ライブラリのスタックトレースを解決したい場合に便利です。
Unity にカスタムシンボルファイルを加えるには、以下を行います。
- Project ウィンドウで、ファイル拡張子が
.soのプラグインを選択します。 - Inspector で Platform settings セクションに移動します。
- CPU にシンボルファイルが対応している CPU アーキテクチャを設定します。
- Shared Library Type を Symbol に設定します。
Unity がシンボルパッケージを生成するたびに、追加シンボルファイルがシンボルパッケージに追加されます。
C# スクリプトからカスタムシンボルファイルを加える場合、UnityEditor.Android 名前空間には CPU と Shared Library Type を設定するため、それぞれ以下の API が含まれています。
ノート: シンボルファイル名は、シンボルファイルの対象となる共有ライブラリの名前と一致する必要があります。例えば、共有ライブラリの名前が mylibrary.so の場合、シンボルファイルの名前もmylibrary.so でなければなりません。ファイル名の衝突を避けるため、シンボルファイルと共有ライブラリは別々のディレクトリに置く必要があります。
重要: シンボルファイルが最新で、実行コードを含む共有ライブラリと互換性があることを確認してください。そうしないと、ローカルデバッガと Google Play は、共有ライブラリ内のコードのスタックトレースを解決できません。
シンボルパッケージの生成
アプリケーションのシンボルパッケージ生成を有効にするには、2 つの方法があります。
- Build Settings (ビルド設定) ウィンドウから。
- EditorUserBuildSettings.androidCreateSymbols API を使用します。
Build Settings ウィンドウでシンボルパッケージ生成を有効にするには、以下を行います。
Build Settings ウィンドウを開きます (メニュー: File > Build Settings)。
Android プラットフォームを選択します。
-
Create symbols.zip に以下のいずれかを設定します。
シンボルパッケージの生成を有効にした後、プロジェクトをビルドし、libmain、libunity、libil2cpp ライブラリ用のシンボルファイルを含む .zip ファイルを生成します。スクリプティングバックエンド を IL2CPP に設定すると、.zip には libil2cpp ライブラリのシンボルファイルも含まれます。Unity はこのシンボルパッケージを出力ディレクトリ内に配置します。
Android Build 設定で Export Project を有効にすると、Unity はプロジェクトのビルドを行いません。代わりに、Android Studio 用にプロジェクトをエクスポートし、libmain と libunity 用のシンボルを作成し、出力ディレクトリの unityLibrary/symbols/<architecture>/ 内に配置します。Android Studio からエクスポートされたプロジェクトをビルドすると、Gradle は libil2cpp シンボルファイルを生成し、libmain と libunity シンボルファイルとともに unityLibrary/symbols/<architecture>/ ディレクトリ内に配置します。
Google Play コンソールでのシンボルの使用
アプリケーションを Google Play にアップロードした後、パブリックシンボル パッケージをアップロードできます。この方法については、Google のドキュメント Deobfuscate or symbolicate crash stack traces を参照してください。
ノート： Google Play では、シンボルパッケージをアップロードする前にアプリケーションが受けたクラッシュはシンボル化されません。