Налагодження нативного коду

Defold ретельно протестовано, і за звичайних обставин аварійні завершення мають траплятися дуже рідко. Однак неможливо гарантувати, що їх ніколи не буде, особливо якщо ваша гра використовує нативні розширення. Якщо ви зіткнулися з аварійними завершеннями або нативним кодом, який працює не так, як очікується, є кілька способів розібратися з проблемою:

• Використайте налагоджувач для покрокового виконання коду
• Скористайтеся налагодженням за допомогою виведення
• Проаналізуйте журнал аварійного завершення
• Відновіть символи стека викликів

Використання налагоджувача

Найпоширеніший спосіб — запускати код через налагоджувач. Він дає змогу виконувати код покроково, встановлювати точки зупинки й зупиняє виконання в разі аварії.

Для кожної платформи є кілька налагоджувачів.

• 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) + платформи з підтримкою gdbserver
• Xcode — macOS, iOS (докладніше)
• Android Studio — Android (докладніше)
• WinDBG — Windows
• lldb/gdb — macOS, Linux, (iOS)
• ios-deploy — iOS (через lldb)

Налагодження за допомогою виведення

Найпростіший спосіб налагодження нативного коду — налагодження за допомогою виведення. Використовуйте функції з простору імен dmLog, щоб відстежувати змінні або позначати перебіг виконання. Будь-яка з функцій журналювання виводитиме повідомлення на панель Console у редакторі та до журналу гри.

Аналіз журналу аварійного завершення

У разі критичної аварії рушій Defold зберігає файл _crash. Цей файл містить інформацію про систему та аварію. У журналі гри буде вказано розташування файлу аварії (воно залежить від операційної системи, пристрою та застосунку).

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

Отримання журналу аварійного завершення з пристрою

Якщо аварія трапилася на мобільному пристрої, ви можете завантажити файл аварії на свій комп’ютер і проаналізувати його локально.

Android

Якщо застосунок дозволяє налагодження, ви можете отримати журнал аварійного завершення за допомогою інструмента Android Debug Bridge (ADB) і команди 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 або файлу журналу, можна відновити в ньому символи (symbolication). Це означає перетворення кожної адреси в стеку викликів на ім’я файлу та номер рядка, що допомагає знайти першопричину.

Важливо використовувати саме той рушій, якому відповідає стек викликів, інакше ви, найімовірніше, шукатимете проблему не там! Використовуйте прапорець --with-symbols під час пакування за допомогою bob або встановіть прапорець Generate debug symbols у діалоговому вікні пакування в редакторі:

• iOS — папка dmengine.dSYM.zip у build/arm64-ios містить налагоджувальні символи для збірок iOS.
• macOS — папка dmengine.dSYM.zip у build/x86_64-macos містить налагоджувальні символи для збірок macOS.
• Android — вихідна папка пакета projecttitle.apk.symbols/lib/ містить налагоджувальні символи для цільових архітектур.
• Linux — виконуваний файл містить налагоджувальні символи.
• Windows — файл dmengine.pdb у build/x86_64-win32 містить налагоджувальні символи для збірок Windows.
• HTML5 — каталог <project_name>_symbols поруч із пакетом HTML5 містить <project_name>_wasm.js.symbols, а якщо вибрано архітектуру wasm_pthread-web, то й <project_name>_pthread_wasm.js.symbols.

Завантаження символів у Google Play

Ви можете завантажити налагоджувальні символи в Google Play, щоб у всіх аварійних завершеннях, зареєстрованих у Google Play, відображалися стеки викликів із відновленими символами. Заархівуйте у форматі ZIP вміст вихідної папки пакета projecttitle.apk.symbols/lib/. Вона містить одну або кілька вкладених папок із назвами архітектур, як-от arm64-v8a, armeabi-v7a і x86_64.

Відновлення символів стека викликів Android

1. Візьміть рушій із папки збірки

	$ ls <project>/build/<platform>/[lib]dmengine[.exe|.so]

1. Розпакуйте в папку:

	$ unzip dmengine.apk -d dmengine_1_2_105

1. Знайдіть адресу в стеку викликів

   Наприклад, у стеку викликів без відновлених символів запис може мати такий вигляд

   #00 pc 00257224 libmy_game_name.so

   Де 00257224 — адреса

2. Визначте, чому відповідає адреса

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

Примітка: якщо ви отримали трасування стека з журналів Android, можливо, вам вдасться відновити символи за допомогою ndk-stack

Відновлення символів стека викликів iOS

1. Якщо ви використовуєте нативні розширення, сервер може надати вам символи (.dSYM) (передайте --with-symbols до bob.jar)

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

1. Якщо ви не використовуєте нативні розширення, завантажте символи стандартного рушія:

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

1. Відновіть символи за допомогою адреси завантаження

   З якоїсь причини просте використання адреси зі стека викликів не працює (тобто з адресою завантаження 0x0)

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

# Neither does specifying the load address directly

		$ 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)