디버거

Android 게임 개발 확장 프로그램을 사용할 때 Visual Studio Debugger(LLDB)로 프로젝트를 디버그합니다.

디버거 실행

디버거를 실행하려면 먼저 Android에서 게임을 빌드, 배포, 실행할 수 있어야 합니다. 자세한 내용은 샘플 실행 섹션을 참고하세요.

디버거 없이 게임이 실행되는지 확인한 후에는 F5를 누르거나 Debug(디버그) 메뉴에서 Start Debugging(디버깅 시작) 항목을 선택하여 디버거를 사용할 수 있습니다. 디버거가 게임에 연결되는 동안 대화상자가 표시됩니다.

디버거를 실행하는 데는 애플리케이션 크기와 시작 시 로드해야 하는 기호의 양에 따라 10초에서 1분 또는 그 이상의 시간이 소요됩니다. 디버거가 일부 Android 라이브러리를 기기에서 호스트 머신으로 다운로드해야 하므로 새 기기에 처음 연결할 때 더 많은 시간이 걸립니다. 새 기기로 처음 시도한 시간이 1분 이상 지속되면 디버그 세션을 취소하고 다시 시작해 보세요.

이런 방식으로 디버거를 실행하면 게임이 Waiting for Debugger(디버거 연결 대기) 모드에서 시작되며 디버거가 연결될 때까지 게임 코드가 실행되지 않습니다. 이를 통해 게임의 초기화 섹션을 디버그할 수도 있습니다.

특정 Visual Studio 디버거 기능에 관한 자세한 정보는 Visual Studio 문서에서 확인할 수 있습니다.

프로세스에 연결

실제 또는 가상 기기에서 이미 실행 중인 게임을 디버그하려면 Visual Studio에서 프로세스에 디버거를 연결할 수 있습니다.

Visual Studio에서 Android 솔루션이 열려 있는지 확인하고 다음을 실행합니다.

  1. Debug(디버그) 메뉴로 이동하여 Attach to Process…(프로세스에 연결…)를 선택합니다.
  2. Transport(연결 형식) 드롭다운에서 Android Game Development Extension(Android 게임 개발 확장 프로그램)을 선택합니다.
  3. Qualifier(연결 대상) 드롭다운에서 Android 기기를 선택합니다.
  4. 사용 가능한 프로세스 목록에서 게임 프로세스를 선택하고 Attach(연결)를 클릭합니다.

프로세스에 연결

LLDB.Shell 명령어 실행

디버깅 세션이 활성화된 상태에서 Visual Studio의 Command Window(명령어 창)를 사용하여 LLDB.Shell 명령어를 실행합니다.

명령어 형식:

LLDB.Shell [command]

예:

>LLDB.Shell expr myIntVariable = 9
Status:  Success
Output Message:
(int) $2 = 9

데이터 시각화

형식 지정자

형식 지정자를 사용하여 Autos(자동), Locals(로컬), Watch(조사식) 및 변수 DataTip(데이터팁) 창에 표시되는 값의 형식을 변경할 수 있습니다.

형식 지정자는 표현식의 끝에 있습니다. 쉼표로 시작하며 짧은 문자열이 이어집니다. 예를 들어, _myInt,x 표현식의 ,x 지정자는 myInt 형식을 소문자로 된 16진수로 지정합니다.

형식 지정자는 Watch(조사식) 창 또는 Autos(자동), Locals(로컬)DataTip(데이터팁) 창에서 Natvis 표현식에 추가하여 직접 사용할 수 있습니다. 자세한 정보는 Natvis를 참고하세요.

지원 지정자 목록

형식 이름 지정자 설명
부울 B 0은 거짓이고 나머지는 모두 참이라는 관례적인 규칙을 사용하여 이것을 참/거짓 부울로 표시합니다.
바이너리 b 비트 시퀀스로 표시합니다.
바이너리, 선행하는 0b 없음 bb 프리픽스 0b가 없는 비트 시퀀스로 표시합니다.
바이트 y 바이트를 표시하지만, ASCII 문자로도 표시하도록 시도합니다.
예: (int *) c.sp.x = 50 f8 bf 5f ff 7f 00 00 P.._....
ASCII가 포함된 바이트 Y 바이트를 표시하지만, ASCII 문자로도 표시하도록 시도합니다.
예: (int *) c.sp.x = 50 f8 bf 5f ff 7f 00 00 P.._....
문자 c 바이트를 ASCII 문자로 표시합니다.
예: (int *) c.sp.x = P\xf8\xbf_\xff\x7f\0\0
인쇄 가능한 문자 C 바이트를 인쇄 가능한 ASCII 문자로 표시합니다.
예: (int *) c.sp.x = P.._....
복합 부동 소수점 수 F 이 값을 복합 부동 소수점 수의 실수부 및 허수부로 해석합니다.
예: (int *) c.sp.x = 2.76658e+19 + 4.59163e-41i
십진수 d, i 부호가 있는 정수로 표시합니다(변환을 실행하지 않고 단순히 부호가 있는 정수로 바이트를 표시함).
열거형 E, en 열거형으로 표시하며, 가능한 경우 값의 이름을 인쇄하고 그렇지 않으면 정숫값을 인쇄합니다.
예: (enum enumType) val_type = eValue2
16진수 - 소문자 x, h 소문자 16진수 표기법으로 표시합니다(변환을 실행하지 않고 단순히 바이트를 16진수로 표시함).
16진수 - 대문자 X, H 대문자 16진수 표기법으로 표시합니다(변환을 실행하지 않고 단순히 바이트를 16진수로 표시함).
16진수 - 소문자, 선행하는 0x 없음 xb, hb 프리픽스 0x 없이 소문자 16진수 표기법으로 표시합니다(변환을 실행하지 않고 단순히 바이트를 16진수로 표시함).
16진수 - 대문자, 선행하는 0x 없음 Xb, Hb 프리픽스 0x 없이 대문자 16진수 표기법으로 표시합니다(변환을 실행하지 않고 단순히 바이트를 16진수로 표시함).
부동 소수점 수 f 부동 소수점 수로 표시합니다(변환을 실행하지 않고 단순히 바이트를 IEEE754 부동 소수점 값으로 해석함).
8진수 o 8진수 표기법으로 표시합니다.
OS Type O MacOS OSType으로 표시합니다.
예: (부동 소수점 수) x = '\n\x1f\xd7\n'
문자열 - C-문자열 s 0으로 끝나는 C 문자열로 표시합니다.
예: 'Hello World'
문자열 - C 문자열, 따옴표 없음 sb 따옴표 없이 0으로 끝나는 C 문자열로 표시합니다.
예: Hello World
문자열 - UTF-8 s8 0으로 끝나는 UTF-8 문자열로 표시합니다.
예: u8'Hello World ☕'
문자열 - UTF-8, 따옴표 없음 s8b 따옴표 없이 0으로 끝나는 UTF-8 문자열로 표시합니다.
예: Hello World ☕
문자열 - UTF-16 su 0으로 끝나는 UTF-16 문자열로 표시합니다.
예: u'Hello World ☕'
문자열 - UTF-16, 따옴표 없음 sub 따옴표 없이 0으로 끝나는 UTF-16 문자열로 표시합니다.
예: Hello World ☕
문자열 - UTF-32 s32 0으로 끝나는 UTF-32 문자열로 표시합니다.
예: U'Hello World ☕'
문자열 - UTF-32, 따옴표 없음 s32b 따옴표 없이 0으로 끝나는 UTF-32 문자열로 표시합니다.
예: Hello World ☕
unicode16 U UTF-16 문자로 표시합니다.
예: (부동 소수점 수) x = 0xd70a 0x411f
unicode32 U32 UTF-32 문자로 표시합니다.
예: (부동 소수점 수) x = 0x411fd70a
부호 없는 십진수 u 부호 없는 정수로 표시합니다(변환을 실행하지 않고 단순히 바이트를 부호가 없는 정수로 표시함).
포인터 p 네이티브 포인터로 표시합니다(실제로 포인터가 아닌 경우 결과 주소는 유효하지 않을 수 있음).
복합 정수 I 복합 정수의 실수부 및 허수부로 해석합니다.
예: (int *) 포인터 = 1048960 + 1i
문자 배열 a 문자 배열로 표시합니다.
예: (char) *c.sp.z = {X}
원시 데이터 ! 원시 데이터 형식, 모든 데이터 유형 뷰 맞춤설정을 무시함

Natvis

Natvis 프레임워크를 사용하면 Visual Studio가 디버거 변수 창에 네이티브 유형을 표시하는 방식을 맞춤설정할 수 있습니다. 예를 들어, Natvis를 사용하여 Watch(조사식), Locals(로컬), Data Tips(데이터팁) 창의 화면을 맞춤설정할 수 있습니다.

Natvis 기능은 기본적으로 사용 설정되어 있지만, Visual Studio에서 Tools(도구) > Options(옵션) > Android Game Development Extension(Android 게임 개발 확장 프로그램) > Natvis 플래그를 Disabled(사용 안함)로 설정하여 사용 중지할 수 있습니다.

Natvis 파일 로드

Visual Studio는 아래 나열된 세 위치에서 Natvis 파일을 로드하고 디버깅 세션을 시작할 때마다 파일을 다시 로드합니다. 파일은 Visual Studio 2017 Natvis 스키마를 준수해야 합니다.

  • 로드된 프로젝트 또는 최상위 솔루션 항목의 일부인 .natvis 파일
  • 사용자별 디렉터리(%USERPROFILE%\Documents\Visual Studio 2017\Visualizers)
  • 시스템 전체 디렉터리(%VSINSTALLDIR%\Common7\Packages\Debugger\Visualizers)
Natvis 파일 새로고침

명령어 창 또는 조사식 창에서 .natvisreload를 평가하여 디버그 세션 중에 Natvis 파일을 다시 로드합니다.

샘플 Natvis 파일

이 샘플 Natvis 파일에는 현재 지원되는 모든 태그와 속성이 포함되어 있습니다.

<?xml version="1.0" encoding="utf-8"?>
<AutoVisualizer xmlns="http://schemas.microsoft.com/vstudio/debugger/natvis/2010">

  <Type Name="demo::Vector&lt;*&gt;">
    <AlternativeType Name="MySimilarVectorType&lt;*&gt;"/>

    <!-- Included to show the <SmartPointer> feature is supported. -->
    <SmartPointer Optional="true" Usage="Minimal">ptr</SmartPointer>

    <!-- Included to show the <DisplayString> feature is supported. -->
    <DisplayString Condition="_size == 0" Optional="true">()</DisplayString>
    <DisplayString Condition="_size == 1">(x={_items[0]})</DisplayString>
    <DisplayString Condition="_size == 2">(x={_items[0]}, y={_items[1]})</DisplayString>
    <DisplayString Condition="_size == 3">(x={_items[0]}, y={_items[1]}, z={_items[2]})</DisplayString>
    <DisplayString>[Size={_size,x}] (x={_items[0]}, y={_items[1]}, z={_items[2]}, ...)</DisplayString>

    <!-- Included to show the <StringView> feature is supported. -->
    <StringView Condition="true" Optional="true">_stringViewText</StringView>

    <Expand HideRawView="false">
      <!-- Included to show the <Item> feature is supported. -->
      <Item Name="X" Condition="_size &lt; 4 &amp;&amp; _size &gt;= 1" Optional="true">_items[0]</Item>
      <Item Name="Y" Condition="_size &lt; 4 &amp;&amp; _size &gt;= 2" Optional="true">_items[1]</Item>
      <Item Name="Z" Condition="_size &lt; 4 &amp;&amp; _size &gt;= 3" Optional="true">_items[2]</Item>

      <!-- Included to show the <ArrayItems> feature is supported. -->
      <ArrayItems Condition="_size >= 4" Optional="true">
        <Size Condition="true" Optional="true">_size</Size>
        <ValuePointer Condition="true">_items</ValuePointer>
      </ArrayItems>

      <!-- Included to show the <IndexListItems> feature is supported. -->
      <IndexListItems Condition="true" Optional="true">
        <Size Condition="true" Optional="true">_listSize</Size>
        <ValueNode Condition="true">_list[%i]</ValueNode>
      </IndexListItems>

      <!-- Included to show the <LinkedListItems> feature is supported. -->
      <LinkedListItems Condition="true" Optional="true">
        <Size Optional="true">_listSize</Size>
        <HeadPointer>_head</HeadPointer>
        <NextPointer>_next</NextPointer>
        <ValueNode>_value</ValueNode>
      </LinkedListItems>

      <!-- Included to show the <ExpandedItem> feature is supported. -->
      <ExpandedItem Condition="true" Optional="true">_childVar</ExpandedItem>

      <!-- Included to show the <Synthetic> feature is supported. -->
      <Synthetic Name="[Size]" Condition="true" Optional="true">
        <DisplayString>_size</DisplayString>
        <Expand HideRawView="true">
          <!-- Any supported <Expand> sub-tags. -->
        </Expand>
      </Synthetic>

      <!-- Included to show the <TreeItems> feature is supported. -->
      <TreeItems Condition="true" Optional="true">
        <Size>_treeSize</Size>
        <HeadPointer>_head</HeadPointer>
        <LeftPointer>_left</LeftPointer>
        <RightPointer>_right</RightPointer>
        <ValueNode>_value</ValueNode>
      </TreeItems>

      <!-- Included to show format specifiers are supported. -->
      <Item Name="[Hex Dump at {_index,x}]">myInt[_index],x</Item>
    </Expand>
  </Type>
</AutoVisualizer>

Natvis 파일 작성

Visual Studio에서는 자체 Natvis 파일 작성을 지원합니다. 자세한 내용은 디버거 변수 창을 맞춤설정하는 방법은 MSDN).

Natvis 파일 디버깅

경우에 따라 오류가 변수의 으로 표시됩니다(예: Auto(자동), Watch(조사식) 등의 창). 예: <error: use of undeclared identifier 'missingVar'>

Android 게임 개발 확장 프로그램 툴바에서 GoogleAndroid.log 파일을 열어 오류에 대한 세부정보를 확인할 수 있습니다.

알려진 제한사항

  • 위에서 예로 든 파일에 나열되지 않은 태그 또는 속성은 현재 지원되지 않는 것입니다. Visual Studio는 지원되지 않는 태그 및 속성을 무시하므로 기존 Natvis 파일에 그대로 둘 수 있으며 스키마를 사용하는 한 파일은 작동합니다.

  • Usage 속성은 스키마에 필요하지만, <SmartPointer>에서 지원되지 않습니다. 그러나 LLDB는 C++에 정의된 연산자에 대한 액세스를 제한하지 않으므로 모든 필수 연산자를 C++로 대신 정의할 수 있습니다.