기술 자료

Unity 엔진

Unity 엔진

Android 기호

빌드된 Android 애플리케이션을 디버깅하는 데 도움이 되는 기호를 생성합니다.
읽는 시간 5분최근 업데이트: 9일 전

애플리케이션 디버깅을 돕기 위해 Unity 네이티브 Unity 라이브러리의 디버그 메타데이터가 포함된 기호 파일이 포함된 패키지를 생성할 수 있습니다. 기호 파일에는 사용 중인 메모리 주소를 메서드 이름과 같이 사용할 수 있는 정보로 변환하는 기호 표(
.symtab
)라는 실행 파일 섹션이 포함되어 있습니다. 변환 프로세스를 심볼화라고 합니다. 기호 패키지를 Google Play 콘솔에 업로드하여 Android Vitals 대시보드에서 사람이 읽을 수 있는 스택 추적을 볼 수 있습니다.
실행 파일(ELF) 섹션에 대한 자세한 내용은 위키피디아를 참조하십시오.
Unity 다음 라이브러리에 대한 기호 파일을 생성합니다.
  • libmain
    : 초기 Unity 엔진 로딩 로직을 담당합니다. 기호 파일이 미리 컴파일되었습니다.
  • libunity
    : Unity 엔진 코드:
    • 엔진 코드 스트립 프로퍼티가 비활성화되면 기호 파일이 미리 컴파일됩니다.
    • 엔진 코드 스트립 프로퍼티가 활성화된 경우, Unity는 빌드 프로세스 동안 기호 파일을 컴파일합니다.
  • libil2cpp
    : C# 스크립트 포함:
    • 프로젝트를 익스포트하지 않으면 Unity 빌드 프로세스 동안 기호 파일을 컴파일합니다.
    • 프로젝트를 익스포트하면 Gradle 기호 파일을 컴파일합니다.
Gradle은 공유 라이브러리에서
.symtab
및
.debug*
실행 파일 섹션을 스트리핑하여 추가 공유 라이브러리에 대한 심볼 파일을 생성합니다. 공유 라이브러리에 이러한 섹션이 포함되어 있지 않으면 Gradle 기호 파일을 생성하지 않습니다.
애플리케이션 빌드 포맷에 따라 Unity 다음 두 가지 방법으로 기호 파일을 생성합니다.
  • apk
    또는
    aab
    모두에 대해 생성할 수 있는 zip 파일로.
  • aab
    에 심볼 파일을 직접 포함합니다. Unity는 기호 파일을
    apk
    에 포함하지 않습니다.
UserBuildSettings.DebugSymbols.format API를 사용하여 기호 패키지의 포맷을 설정합니다.

기호 파일 타입

Unity는 Gradle의 debugSymbolLevel 프로퍼티를 사용하여 기호 파일을 생성합니다. 다음 두 가지 타입의 기호 파일이 있습니다.
  • 공개: 기호 표 섹션이 포함된 작은 파일입니다. 자세한 내용은 공용 기호를 참조하십시오.
  • 디버깅 공용 심볼 파일에 포함된 모든 내용과 더 뎁스 디버깅에 사용할 수 있는 전체 디버깅 정보를 포함합니다. 자세한 내용은 디버깅 심볼을 참조하십시오.
필요한 타입의 기호 파일을 생성하려면 UserBuildSettings.DebugSymbols.level을 사용합니다.
참고
기본적으로 Gradle은
.so.sym
또는
.so.dbg
확장자를 사용하여 기호 파일을 생성합니다. 일부 디지털 배포 서비스는 이러한 확장자를 인식하지 않으며
.so
확장자가 있는 파일이 필요합니다. 이러한 경우 Unity.Android.Types.DebugSymbolFormat.LegacyExtensions API를 사용하여
.so
확장자가 있는 기호 파일을 생성합니다.
UserBuildSettings.DebugSymbols.format = DebugSymbolFormat.IncludeInBundle | DebugSymbolFormat.Zip | DebugSymbolFormat.LegacyExtensions;

공개 심볼

공용 심볼 파일에는 함수 주소를 사람이 읽을 수 있는 문자열로 확인하는 정보가 포함되어 있습니다. 이 파일에는 디버깅 정보가 없습니다. 이렇게 하면 공용 기호 파일이 디버깅 기호 파일보다 작아집니다.

Debugging symbols

디버깅 심볼 파일에는 전체 디버깅 정보와 심볼 표 섹션이 포함되어 있습니다. 이를 사용하여 다음을 수행할 수 있습니다.
  • 스택 추적을 해결하고 소스 코드를 사용할 수 있는 애플리케이션을 디버깅합니다.
  • 애플리케이션에 네이티브 디버거를 연결하고 코드를 디버그합니다.
참고
디버깅 심볼을 사용할 수 없는 경우 Unity 빌드 시점에 프로젝트에 공용 심볼 파일을 배치합니다.
libmain
및
libunity
라이브러리의 경우 디버깅 심볼을 사용할 수 없으며 Unity는 항상 공용 파일을 생성합니다.

커스텀 심볼

추가 기호 파일을 포함하도록 Unity 지시할 수 있습니다. 공유 라이브러리를 사용하고 애플리케이션 크래시 시 로컬 디버거와 google play 공유 라이브러리 스택 추적을 확인하려는 경우에 유용합니다.
Unity 커스텀 심볼 파일을 포함하려면 다음 단계를 따르십시오.
  1. 프로젝트 창에서
    .so
    파일 확장자가 있는 플러그인을 선택합니다.
  2. 인스펙터에서 플랫폼 설정 섹션을 찾습니다.
  3. 기호 파일이 호환되는 CPU 아키텍처로 CPU를 설정합니다.
  4. 공유 라이브러리 타입을 심볼으로 설정합니다.
Unity 심볼 패키지를 생성할 때마다 심볼 패키지에 추가 심볼 파일을 추가합니다.
중요
Shared Library Type을 Executable으로 설정하고 공유 라이브러리에
.symtab
및
.debug*
실행 파일 섹션이 포함된 경우 Gradle은 커스텀 심볼 파일을 덮어쓰는 심볼 파일을 생성합니다.
C# 스크립트에서 Unity에 커스텀 심볼 파일을 포함하려면 UnityEditor.Android 네임스페이스에 각각 CPU 및 공유 라이브러리 타입을 설정하기 위한 다음 API가 포함되어 있습니다.
참고
심볼 파일 이름은 심볼 파일이 사용되는 공유 라이브러리의 이름과 일치해야 합니다. 예를 들어 공유 라이브러리의 이름이 mylibrary.so인 경우 심볼 파일의 이름도 mylibrary.so여야 합니다. 파일 이름 충돌을 방지하려면 기호 파일과 공유 라이브러리가 별도의 디렉토리에 있어야 합니다.
중요
심볼 파일이 최신 상태이며 실행 코드가 포함된 공유 라이브러리와 호환되었는지 확인합니다. 그렇지 않으면 로컬 디버거와 google play 공유 라이브러리의 코드 스택 추적을 확인할 수 없습니다.

Custom plug-in in the Inspector.

심볼 패키지 생성

다음 두 가지 방법으로 애플리케이션에 심볼 패키지 생성을 활성화할 수 있습니다.
Build Profiles 창을 통해 심볼 패키지 생성을 활성화하려면 다음 단계를 따르십시오.
  1. 빌드 프로파일 창을 엽니다(메뉴: 파일 > 빌드 프로필).
  2. Platforms 패널의 플랫폼 목록에서 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
는
MyApp
가 애플리케이션 빌드 파일의 이름이고,
0.1
는 버전이고,
100
는 번들 버전 코드입니다. 버전 및 번들 버전 코드는 Android 플레이어 설정에서 설정됩니다.
Android 빌드 설정에서 Export Project를 활성화하면 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;

압축된 기호

압축된 기호 패키지를 생성하려면 다음 코드를 사용하십시오.
UserBuildSettings.DebugSymbols.level = DebugSymbolLevel.SymbolTable;UserBuildSettings.DebugSymbols.format = DebugSymbolFormat.Zip | DebugSymbolFormat.LegacyExtensions;
애플리케이션을 Google Play에 업로드한 후에는 public symbols zip 패키지를 업로드할 수 있습니다. 이를 수행하는 방법에 대한 자세한 내용은 Google 기술 자료를 참고하십시오. 크래시 스택 추적을 난독화하거나 기호화합니다.
참고
google play 심볼 패키지를 업로드하기 전에 애플리케이션이 수신한 크래시를 기호화하지 않습니다.