Отладчик

Выполняйте отладку проекта с помощью отладчика Visual Studio (LLDB) при использовании расширения для разработки игр для Android.

Запустите отладчик

Прежде чем вы сможете запустить отладчик, вы должны уметь создавать, развертывать и запускать игру на Android. Подробности см. в разделе «Запуск образца» .

Убедившись, что вы можете запустить игру без отладчика, вы можете использовать отладчик, нажав F5 или выбрав пункт «Начать отладку» в меню «Отладка» . Вы должны увидеть диалоговое окно, пока отладчик подключается к игре.

Запуск отладчика занимает от 10 секунд до 1 минуты и более в зависимости от размера вашего приложения и количества символов, которые необходимо загрузить при запуске. При первом подключении к новому устройству требуется больше времени, поскольку отладчику приходится загружать некоторые библиотеки Android с устройства на хост-компьютер. Если первые несколько попыток с новым устройством занимают более 1 минуты, рассмотрите возможность отмены сеанса отладки, а затем перезапускаете его.

Когда вы запускаете отладчик таким образом, игра запускается в режиме ожидания отладчика и не будет выполнять какой-либо код вашей игры до тех пор, пока не подключится отладчик. Это позволит вам также отладить раздел инициализации вашей игры.

Дополнительную информацию о конкретных функциях отладчика Visual Studio можно найти, прочитав документацию Visual Studio .

Присоединение к процессу

Если вы хотите отладить игру, которая уже запущена на физическом или виртуальном устройстве, вы можете подключить к процессу отладчик из Visual Studio.

В Visual Studio убедитесь, что решение Android открыто, и:

  1. Перейдите в меню «Отладка» и выберите «Присоединить к процессу...» .
  2. В раскрывающемся списке «Транспорт» выберите «Расширение разработки игр для Android» .
  3. В раскрывающемся списке «Квалификатор» выберите свое устройство Android.
  4. Выберите игровой процесс из списка доступных процессов и нажмите « Прикрепить» .

Присоединиться к процессу

Выполнение команд LLDB.Shell

При активном сеансе отладки используйте командное окно Visual Studio для запуска команд LLDB.Shell.

Формат команды:

LLDB.Shell [command]

Пример:

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

Визуализация данных

Спецификаторы формата

Вы можете изменить формат, в котором значение отображается в окнах Autos , Locals , Watch и переменных DataTip , с помощью спецификаторов формата.

Спецификаторы формата находятся в конце выражений. Они начинаются с запятой, за которой следует короткая строка. Например, спецификатор ,x в выражении _myInt,x отформатирует myInt как шестнадцатеричное число в нижнем регистре.

Спецификаторы формата можно использовать непосредственно в окне Watch или в окнах Autos , Locals и DataTip , добавив их в выражения Natvis. См. Natvis для получения дополнительной информации.

Список спецификаторов поддержки

Имя формата Спецификатор(ы) Описание
логическое значение Б покажите это как логическое значение true/false, используя обычное правило, согласно которому 0 является ложным, а все остальное — истинным.
двоичный б покажите это как последовательность битов
двоичный, без лидирующего 0b бб покажите это как последовательность битов без префикса 0b
байты й покажите байты, но попробуйте отобразить их также как символы ASCII
например (int *) c.sp.x = 50 f8 bf 5f ff 7f 00 00 P.._....
байты с ASCII Да покажите байты, но попробуйте отобразить их также как символы ASCII
например (int *) c.sp.x = 50 f8 bf 5f ff 7f 00 00 P.._....
характер с показывать байты как символы ASCII
например (int *) c.sp.x = P\xf8\xbf_\xff\x7f\0\0
печатный персонаж С показывать байты как печатные символы ASCII
например (int *) c.sp.x = P.._....
сложное поплавок Ф интерпретируйте это значение как действительную и мнимую часть комплексного числа с плавающей запятой
например (int *) c.sp.x = 2.76658e+19 + 4.59163e-41i
десятичный д, я покажите это как целое число со знаком (это не выполняет приведение, оно просто показывает байты как целое число со знаком)
перечисление Э, ан покажите это как перечисление, печатая имя значения, если оно доступно, или целочисленное значение в противном случае.
например (enum enumType) val_type = eValue2
шестнадцатеричный - маленький регистр х, ч покажите это в шестнадцатеричном виде строчными буквами (приведение не выполняется, а просто показывает байты в шестнадцатеричном виде)
шестнадцатеричный - верхний регистр Х, Ч покажите это в шестнадцатеричной записи заглавными буквами (приведение не выполняется, а просто показывает байты в шестнадцатеричном виде)
шестнадцатеричный - маленький регистр, без начального 0x хб, хб покажите это в шестнадцатеричном виде строчными буквами без префикса 0x (приведение не выполняется, просто отображаются байты в шестнадцатеричном виде)
шестнадцатеричный - верхний регистр, без ведущего 0x Хб, Хб покажите это в шестнадцатеричной записи в верхнем регистре без префикса 0x (это не выполняет приведение, оно просто показывает байты в шестнадцатеричном виде)
плавать ж покажите это как число с плавающей запятой (это не выполняет приведение, оно просто интерпретирует байты как значение с плавающей запятой IEEE754)
восьмеричный о покажите это в восьмеричной записи
Тип ОС О покажите это как OSType MacOS
например (float) x = '\n\x1f\xd7\n'
строка - C-строка с покажите это как строку C с 0-м завершением
например «привет, мир»
string - C-строка, без кавычек сб покажите это как строку C с 0-м завершением без кавычек,
например, привет, мир
строка — UTF-8 s8 покажите это как строку UTF-8 с нулевым завершением
например u8"привет мир ☕"
строка — UTF-8, без кавычек s8b покажите это как строку UTF-8 с нулевым завершением без кавычек
например, привет, мир ☕
строка — UTF-16 Су покажите это как строку UTF-16 с нулевым завершением
например, ты "привет, мир ☕"
строка — UTF-16, без кавычек суб покажите это как строку UTF-16 с нулевым завершением без кавычек
например, привет, мир ☕
строка — UTF-32 s32 покажите это как строку UTF-32 с нулевым завершением
например: U"привет, мир ☕"
строка — UTF-32, без кавычек s32b покажите это как строку UTF-32 с нулевым завершением без кавычек
например, привет, мир ☕
юникод16 ты покажите это как символы UTF-16
например (с плавающей запятой) x = 0xd70a 0x411f
юникод32 U32 покажите это как символы UTF-32
например (с плавающей запятой) x = 0x411fd70a
беззнаковая десятичная дробь ты покажите это как целое число без знака (это не выполняет приведение, оно просто показывает байты как целое число без знака)
указатель п покажите это как собственный указатель (если это действительно указатель, результирующий адрес, вероятно, будет недействительным)
комплексное целое число я интерпретируйте это значение как действительную и мнимую часть комплексного целого числа.
например (int *) указатель = 1048960 + 1i
массив символов а покажите это как массив символов
например (символ) *c.sp.z = {X}
Сырой ! необработанный формат, игнорируя любые настройки представлений типов данных

Натвис

Платформа Natvis позволяет настраивать способ отображения собственных типов Visual Studio в окнах переменных отладчика. Например, используйте Natvis для настройки отображения окон Watch , Locals и Data Tips .

Функция Natvis включена по умолчанию, но ее можно отключить в Visual Studio, установив для параметра «Инструменты» > «Параметры» > «Расширение разработки игр для Android» > флаг Natvis значение «Отключено» .

Загрузка файлов Natvis

Visual Studio загружает файлы Natvis из трех мест, перечисленных ниже, и перезагружает их каждый раз при запуске сеанса отладки. Файлы должны соответствовать схеме Visual Studio 2017 Natvis.

  • Файлы .natvis , являющиеся частью загруженного проекта или элемента решения верхнего уровня.
  • Каталог пользователя ( %USERPROFILE%\Documents\Visual Studio 2017\Visualizers )
  • Общесистемный каталог ( %VSINSTALLDIR%\Common7\Packages\Debugger\Visualizers )
Перезагрузка файлов Natvis

Перезагрузите файлы Natvis во время сеанса отладки, оценив .natvisreload в командном окне или окне просмотра.

Пример файла 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'>

Более подробную информацию об ошибке можно получить, открыв файл GoogleAndroid.log на панели инструментов расширения Android Game Development Extension.

Известные ограничения

  • Если ваш тег или атрибут не указан в приведенном выше файле примера, он в настоящее время не поддерживается. Visual Studio игнорирует неподдерживаемые теги и атрибуты, поэтому вы можете оставить их в существующем файле Natvis, и файл будет работать, пока он использует нашу схему.

  • Атрибут Usage , хотя и требуется схемой, не поддерживается для <SmartPointer> . Однако LLDB не ограничивает доступ к операторам, определенным в C++, поэтому вместо этого любой требуемый оператор может быть определен в C++.