Read this manual in English

Отладка нативного кода

Defold неплохо протестирован и очень редко дает сбой при нормальных обстоятельствах. Однако невозможно гарантировать, что он никогда не выйдет из строя, особенно если ваша игра использует нативные расширения. Если вы столкнетесь с проблемами, связанными со сбоями или собственным кодом, который ведет себя не так, как ожидалось, есть несколько способов продвинуться с проблемой:

  • Используйте отладчик для пошагового выполнения кода
  • Используйте отладочный вывод
  • Анализируйте логи сбоев
  • Сгенерируйте отладочные символы к стеку вызовов

Использование отладчика

Самый распространенный способ - запустить код через отладчик. Он позволяет вам пройти по коду, установить точки останова (breakpoints) и он остановит выполнение, если вы получите сбой.

Для каждой платформы существует несколько отладчиков.

  • Visual studio - Windows
  • VSCode - Windows, macOS, Linux
  • Android Studio - Windows, macOS, Linux
  • Xcode - macOS
  • WinDBG - Windows
  • lldb / gdb - macOS, Linux, (Windows)
  • ios-deploy - macOS

Каждый инструмент может отлаживать определенные платформы:

  • Visual studio - Windows + платформы с поддержкой gdbserver (например, Linux/Android)
  • VSCode - Windows, macOS (lldb), Linux (lldb/gdb) + платформы с поддержкой gdbserve
  • Xcode - macOS, iOS (узнать больше)
  • Android Studio - Android (узнать больше)
  • WinDBG - Windows
  • lldb/gdb - macOS, Linux, (iOS)
  • ios-deploy - iOS (via lldb)

Применение отладочного вывода

Самый простой способ отладки нативного кода - использовать отладочную печать. Используйте функции в пространстве имен dmLog, чтобы наблюдать за переменными или обозначать поток выполнения. Использование любой из функций логирования приведет к печати в секции Console в редакторе и в лог игры.

Анализ лога сбоя

Движок Defold сохраняет файл _crash в случае серьезного сбоя. crash файл будет содержать информацию о системе, а также о сбое. В выводе лога игры будет записано, где находится crash файл (это зависит от операционной системы, устройства и приложения).

Вы можете использовать crash модуль, чтобы прочитать этот файл в следующей сессии. Рекомендуется прочитать файл, собрать информацию, вывести ее в консоли и отправить в сервисы аналитики, которые поддерживают сбор crash логов.

В Windows также создается файл _crash.dmp. Этот файл полезен при отладке сбоя.

Получение лога сбоев с устройства

Если сбой происходит на мобильном устройстве, вы можете загрузить crash файл на свой компьютер и проанализировать его локально.

Android

Если приложение в режиме отладки, вы можете получить лог сбоев с помощью Android Debug Bridge (ADB) tool и команды adb shell:

	$ adb shell "run-as com.defold.example sh -c 'cat /data/data/com.defold.example/files/_crash'" > ./_crash

iOS

В iTunes вы можете просмотреть/загрузить контейнер приложений.

В окне Xcode -> Devices вы также можете выбрать логи сбоев.

Генерация отладочных символов к стеку вызовов

Если вы получили стек вызовов либо из файла _crash, либо из лог файла, вы можете сгенерировать отладочные символы. Это означает перевод каждого адреса в стеке вызовов в имя файла и номер строки, что, в свою очередь, помогает при обнаружении основной причины падения.

Очень важно, чтобы вы сопоставили правильный движок со стеком вызовов. В противном случае очень вероятно, что вы получите неверную отладку. Если вы работаете с нативными расширениями, не забудьте добавить флаг –with-symbols к утилите bob или установите флажок “Generate debug symbols” в диалоговом окне пакета в редакторе, чтобы получить все необходимые данные с сервера сборки:

  • iOS и macOS - папка dmengine.dSYM в build.zip содержит символы отладки для сборок под iOS/macOS.
  • Android и Linux - сами исполняемые файлы содержат символы отладки.
  • Windows - файл dmengine.pdb в архиве ` build.zip` содержит символы отладки для сборок под Windows.
  • HTML5 - файл dmengine.js.symbols в архиве build.zip содержит символы отладки для сборок под HTML5.

Если вы делаете сборки без нативных расширений, символы отладки доступны на веб-сайте для скачивания Defold:

  • iOS - Файлы engine/armv7-darwin/dmengine_release.dSYM.zip и engine/arm64-darwin/dmengine_release.dSYM.zip содержат символы отладки для 32- и 64-битных версий движка.
  • macOS - Файл engine/x86_64-darwin/dmengine_release.dSYM.zip содержит символы отладки.
  • Android - Файлы движков engine/armv7-android/dmengine.apk и engine/arm64-android/dmengine.apk включают символы отладки для 32- и 64-битных версий движка.
  • Linux - Файл движка engine/x86_64-linux/dmengine_release включает символы отладки.
  • Windows - Файл engine/x86_64-win32/dmengine_release.pdb содержит символы отладки.
  • HTML5 - Файл engine/js-web/dmengine_release.js.symbols содержит символы отладки.

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

Генерация отладочных символов к стеку вызовов Android

  1. Получите его из папки сборки

    $ ls /build//[lib]dmengine[.exe|.so]

  2. Распакуйте архив:

    $ unzip dmengine.apk -d dmengine_1_2_105

  3. Найдите адрес в стеке вызовов

    Например, в стеке вызовов без отладочных символов это могло бы выглядеть так

    #00 pc 00257224 libmy_game_name.so

    Где 00257224 это адрес

  4. Обработайте этот адрес командой

    $ arm-linux-androideabi-addr2line -C -f -e dmengine_12_105/lib/armeabi-v7a/libdmengine.so _address

Примечание: Если вы получите стектрейс из логов Android, вы можете снабдить его отладочными символами с помощью ndk-stack.

Генерация отладочных символов к стеку вызовов iOS

  1. Если вы используете нативные расширения, сервер может предоставить вам символы (.dSYM) (передайте ключ --with-symbols в bob.jar)

    $ unzip /build/arm64-darwin/build.zip # it will produce a Contents/Resources/DWARF/dmengine

  2. Если вы не используете нативные расширения, скачайте стандартные отладочные символы:

    $ wget http://d.defold.com/archive//engine/arm64-darwin/dmengine.dSYM

  3. Получите отладочные символы, используя адрес загрузки

    По какой-то причине простое добавление адреса из стека вызовов не работает (т. е. адрес загрузки 0x0)

     $ atos -arch arm64 -o Contents/Resources/DWARF/dmengine 0x1492c4
    

    # Также никакого результата не даст задание адреса загрузки напрямую

     $ atos -arch arm64 -o MyApp.dSYM/Contents/Resources/DWARF/MyApp -l0x100000000 0x1492c4
    

    Добавление адреса загрузки к адресу из стека вызовов даст нужный результат:

     $ atos -arch arm64 -o MyApp.dSYM/Contents/Resources/DWARF/MyApp 0x1001492c4
     dmCrash::OnCrash(int) (in MyApp) (backtrace_execinfo.cpp:27)