ドキュメント

Unity Engine

Unity Engine

Android シンボル

ビルドした Android アプリケーションのデバッグにヘルプシンボルを生成します。
読み終わるまでの所要時間 16 分最終更新 5日前

アプリケーションのデバッグをヘルプするために、Unity はネイティブの Unity ライブラリのデバッグメタデータを持つシンボルファイルを含むパッケージを生成できます。シンボルファイルには、シンボル表 (
.symtab
) と呼ばれる実行ファイルセクションが含まれ、アクティブなメモリーアドレスをメソッド名などの情報に変換します。翻訳プロセスはシンボル化と呼ばれます。シンボルパッケージを google play コンソールにアップロードすると、人間が判読可能なスタックトレースが Android Vitals ダッシュボードに表示されます。
実行ファイル (ELF) セクションの詳細については、Wikipedia を参照してください。
Unity は以下のライブラリのシンボルファイルを生成します。
  • libmain
    : Unity エンジンの初期ロード ロジックを担当します。シンボルファイルはプリコンパイルされます。
  • libunity
    : Unity のエンジンコード:
    • ストリップエンジンコードプロパティが無効の場合、シンボルファイルはプリコンパイルされます。
    • ストリップエンジンコードプロパティが有効になっている場合、Unity はビルドプロセス中にシンボルファイルをコンパイルします。
  • libil2cpp
    : C# スクリプトが含まれています。
    • プロジェクトをエクスポートしない場合、Unity はビルドプロセス中にシンボルファイルをコンパイルします。
    • プロジェクトをエクスポートする場合、Gradle はシンボルファイルをコンパイルします。
Gradle は、共有ライブラリから
.symtab
実行ファイルセクションと
.debug*
実行ファイルセクションをストリッピングすることで、追加の共有ライブラリのシンボルファイルを生成します。共有ライブラリにこれらのセクションが含まれていない場合、Gradle はそのセクションのシンボルファイルを生成しません。
アプリケーションのビルド形式に応じて、Unity は 2 つの方法でシンボルファイルを生成します。
  • apk
    または
    aab
    の両方に対して生成できる zip ファイル。
  • シンボルファイルを
    aab
    に直接埋め込みます。Unity はシンボルファイルを
    apk
    に埋め込みません。
UserBuildSettings.DebugSymbols.形式 API を使用して、シンボルパッケージの形式を設定します。

シンボルファイルの種類

Unity は Gradle の debugSymbolLevel プロパティを使用してシンボルファイルを生成します。シンボルファイルには 2 種類があります。
  • Publicシンボルテーブルセクションを含む小さなファイル。詳細については、パブリックシンボル を参照してください。
  • デバッグパブリックシンボルファイルに含まれるすべてと、より深度なデバッグに使用できる完全なデバッグ情報が含まれています。詳細は、「 デバッグシンボル 」を参照してください。
UserBuildSettings.DebugSymbols.level を使用して、必要な種類のシンボルファイルを生成します。
注
デフォルトでは、Gradle は
.so.sym
または
.so.dbg
拡張子を持つシンボルファイルを生成します。一部のデジタル分布サービスはこれらの拡張子を認識せず、
.so
拡張子のファイルを必要とします。そのような場合は、Unity.Android.Types.DebugSymbolFormat.LegacyExtensions API を使用して、
.so
拡張子を持つシンボルファイルを作成します。
UserBuildSettings.DebugSymbols.形式 = DebugSymbolFormat.IncludeInBundle | DebugSymbolFormat.Zip | DebugSymbolFormat.LegacyExtensions;

パブリックシンボル

パブリックシンボルファイルには、機能アドレスを人間が読める文字列に解決する情報が含まれています。これらのファイルにはデバッグ情報は含まれません。これにより、パブリックシンボルファイルはデバッグシンボルファイルよりも小さくなります。

Debugging symbols (デバッグシンボル)

デバッグシンボルファイルには、完全なデバッグ情報とシンボル表セクションが含まれています。これを使用して以下を行います。
  • スタックトレースを解決し、ソースコードを使用できるアプリケーションをデバッグする。
  • アプリケーションにネイティブをアタッチ、設定、添付し、コードをデバッグします。
注
デバッグシンボルを使用できない場合、Unity はビルド時に パブリックシンボル ファイルをプロジェクトに配置します。
libmain
ライブラリと
libunity
ライブラリでは、デバッグシンボルは使用できません。Unity は常に公開ファイルを生成します。

カスタムシンボル

Unity に追加のシンボル ファイルを含めるように指示できます。これは、共有ライブラリを使用していて、ローカルデバッガと google play でアプリケーションがクラッシュしたときに共有ライブラリのスタックトレースを解決したい場合に便利です。
Unity にカスタムシンボルファイルを含めるには、以下を行います。
  1. Project ウィンドウで、
    .so
    ファイル拡張子を持つプラグインを選択します。
  2. Inspector で、プラットフォーム設定セクションを見つけます。
  3. CPU をシンボル ファイルと互換性のある CPU アーキテクチャに設定します。
  4. 共有ライブラリタイプをシンボルに設定します。
Unity がシンボル パッケージを生成するたびに、シンボル パッケージに追加のシンボル ファイルを追加します。
重要
共有ライブラリの種類 を 実行ファイル に設定し、共有ライブラリに
.symtab
実行ファイルセクションと
.debug*
実行ファイルセクションが含まれている場合、Gradle はカスタムシンボルファイルを上書きするシンボルファイルを生成します。
Unity に C# スクリプトのカスタムシンボルファイルを含める場合は、UnityEditor.Android 名前空間に以下の API が含まれ、それぞれ CPU と共有ライブラリタイプを設定します。
注
シンボル ファイル名は、シンボル ファイルの対象となる共有ライブラリの名前と一致する必要があります。例えば、共有ライブラリの名前が mylibrary.so の場合、シンボルファイルの名前も mylibrary.so である必要があります。ファイル名の衝突を避けるために、シンボル ファイルと共有ライブラリは別のディレクトリに置く必要があります。
重要
シンボルファイルが最新であり、実行ファイルコードを含む共有ライブラリと互換性のあることを確認します。そうしないと、ローカルデバッガと google play で共有ライブラリのコードのスタックトレースの解決に失敗します。

Custom plug-in in the Inspector.

シンボルパッケージの生成

アプリケーションのシンボルパッケージ生成を有効にするには、2 つの方法があります。
ビルドプロファイルウィンドウでシンボルパッケージの生成を有効にするには、次の手順に従います。
  1. ビルドプロファイルウィンドウ (メニュー:ファイル> ビルドプロファイル)。
  2. 「プラットフォーム」パネルのプラットフォームのリストから、Android を選択するか、Android プラットフォームのビルドプロファイルを作成します。
  3. デバッグシンボルを以下のいずれかに設定します。
  4. シンボル出力オプションを .zip に設定します。
シンボルパッケージの生成を有効にした後、プロジェクトを構築すると、
libmain
および
libunity
ライブラリのシンボルファイルを含む
.zip
ファイルが生成されます。スクリプティングバックエンドを
IL2CPP

?

に設定すると、
.zip
には
libil2cpp
ライブラリのシンボルファイルも含まれます。Unity はこのシンボル パッケージを出力ディレクトリ内に配置します。シンボル パッケージ ファイルの名前は、
<appbuildfilename>-<version>-v<bundle version code>-IL2CPP.symbols.zip
の形式です。例えば、
MyApp-0.1-v100-IL2CPP.symbols.zip
はアプリケーションビルドファイルの名前、
0.1
はバージョン、
100
はバンドルバージョンコードです。
MyApp
バージョンとバンドルのバージョンコードは、Android プレイヤー設定で設定します。
Android のビルド設定でエクスポートプロジェクトを有効にすると、Unity はプロジェクトをビルドしません。代わりに、プロジェクトを Android Studio 用にエクスポートし、
libmain
と
libunity
のシンボルを生成し、出力ディレクトリの
unityLibrary/symbols/<architecture>/
内に配置します。Android Studio からエクスポートしたプロジェクトをビルドすると、Gradle によって
libil2cpp
シンボルファイルが生成され、
libmain
および
libunity
シンボルファイルとともに
unityLibrary/symbols/<architecture>/
ディレクトリ内に配置されます。

google play コンソールでのシンボルの使用

埋め込まれたシンボル

Android アプリバンドル (aab) を作成する場合は、シンボルを
aab
に直接埋め込み、google play にアップロードできます。
注
Unity はシンボルを
apk
に埋め込みません。この場合、シンボルを含む zip ファイルを別にアップロードする必要があります。
UserBuildSettings.DebugSymbols.level = DebugSymbolLevel.SymbolTable;UserBuildSettings.DebugSymbols.format = DebugSymbolFormat.IncludeInBundle;

Zip 圧縮されたシンボル

圧縮されたシンボルパッケージを生成するには、以下のコードを使用します。
UserBuildSettings.DebugSymbols.level = DebugSymbolLevel.SymbolTable;UserBuildSettings.DebugSymbols.format = DebugSymbolFormat.Zip | DebugSymbolFormat.LegacyExtensions;
アプリケーションを google play にアップロードしたら、public symbols zip パッケージをアップロードできます。この方法については、Google のドキュメントを参照してください。クラッシュスタックトレースを解読または記号化します。
注
google play は、シンボルパッケージのアップロード前にアプリケーションが受けたクラッシュを象徴しません。