Yerel kodda hata ayıklama

Defold kapsamlı biçimde test edilmiştir ve normal koşullarda çok nadiren çökmesi beklenir. Ancak özellikle oyununuz yerel kod eklentileri (native extensions) kullanıyorsa, hiçbir zaman çökmeyeceğini garanti etmek mümkün değildir. Çökmelerle veya beklediğiniz gibi davranmayan yerel kodla (native code) ilgili sorunlarla karşılaşırsanız başvurabileceğiniz birkaç farklı yöntem vardır:

• Kodda adım adım ilerlemek için bir hata ayıklayıcı kullanın
• Çıktı yazdırarak hata ayıklayın
• Bir çökme günlüğünü inceleyin
• Bir çağrı yığınına sembol çözümlemesi uygulayın

Hata ayıklayıcı kullanma

En yaygın yöntem, kodu bir hata ayıklayıcı (debugger) aracılığıyla çalıştırmaktır. Kodda adım adım ilerlemenizi ve kesme noktaları (breakpoints) belirlemenizi sağlar; bir çökme yaşanırsa yürütmeyi durdurur.

Her platform için çeşitli hata ayıklayıcılar vardır.

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

Her araç belirli platformlarda hata ayıklayabilir:

• Visual studio - Windows + gdbserver destekleyen platformlar (ör. Linux/Android)
• VSCode - Windows, macOS (lldb), Linux (lldb/gdb) + gdbserver destekleyen platformlar
• Xcode - macOS, iOS (daha fazla bilgi)
• Android Studio - Android (daha fazla bilgi)
• WinDBG - Windows
• lldb/gdb - macOS, Linux, (iOS)
• ios-deploy - iOS (lldb aracılığıyla)

Çıktı yazdırarak hata ayıklama

Yerel kodunuzda hata ayıklamanın en basit yolu, çıktı yazdırarak hata ayıklama (print debugging) yöntemini kullanmaktır. Değişkenleri izlemek veya yürütme akışını belirtmek için dmLog ad alanındaki işlevleri kullanın. Günlük işlevlerinden herhangi biri kullanıldığında, düzenleyicideki Console görünümüne ve oyun günlüğüne çıktı yazdırılır.

Çökme günlüğünü inceleme

Defold motoru, kurtarılamayan bir çökme yaşarsa bir _crash dosyası kaydeder. Çökme dosyası, çökmeyle ilgili bilgilerin yanı sıra sistemle ilgili bilgileri de içerir. Oyun günlüğü çıktısı, çökme dosyasının konumunu belirtir (bu konum işletim sistemine, cihaza ve uygulamaya göre değişir).

Bu dosyayı bir sonraki oturumda okumak için crash modülünü kullanabilirsiniz. Dosyayı okumanız, bilgileri toplamanız, konsola yazdırmanız ve çökme günlüklerinin toplanmasını destekleyen bir analiz hizmetine göndermeniz önerilir.

Bir cihazdan çökme günlüğünü alma

Bir mobil cihazda çökme yaşanırsa, çökme dosyasını kendi bilgisayarınıza indirip yerel olarak ayrıştırmayı seçebilirsiniz.

Android

Uygulamada hata ayıklama etkinse, Android Debug Bridge (ADB) aracını ve adb shell komutunu kullanarak çökme günlüğünü alabilirsiniz:

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

iOS

iTunes’ta bir uygulamanın kapsayıcısını (container) görüntüleyebilir/indirebilirsiniz.

Xcode -> Devices penceresinde çökme günlüklerini de seçebilirsiniz

Çağrı yığınına sembol çözümlemesi uygulama

Bir _crash dosyasından veya bir günlük dosyasından çağrı yığını (callstack) elde ederseniz, buna sembol çözümlemesi (symbolication) uygulayabilirsiniz. Bu işlem, çağrı yığınındaki her adresi bir dosya adına ve satır numarasına dönüştürür; böylece sorunun asıl nedenini bulmanıza yardımcı olur.

Çağrı yığınını doğru motorla eşleştirmeniz önemlidir; aksi takdirde büyük olasılıkla yanlış yerlerde hata ayıklamaya çalışırsınız! --with-symbols seçeneğini bob ile paketleme yaparken kullanın veya düzenleyicideki paketleme iletişim kutusunda “Generate debug symbols” onay kutusunu işaretleyin:

• iOS - dmengine.dSYM.zip klasörü, build/arm64-ios içinde bulunur ve iOS derlemelerinin hata ayıklama sembollerini içerir.
• macOS - dmengine.dSYM.zip klasörü, build/x86_64-macos içinde bulunur ve macOS derlemelerinin hata ayıklama sembollerini içerir.
• Android - projecttitle.apk.symbols/lib/ dağıtım paketi çıktı klasörü, hedef mimarilerin hata ayıklama sembollerini içerir.
• Linux - yürütülebilir dosya, hata ayıklama sembollerini içerir.
• Windows - dmengine.pdb dosyası, build/x86_64-win32 içinde bulunur ve Windows derlemelerinin hata ayıklama sembollerini içerir.
• HTML5 - HTML5 dağıtım paketinin yanındaki <project_name>_symbols dizini, <project_name>_wasm.js.symbols dosyasını ve wasm_pthread-web mimarisi seçildiğinde <project_name>_pthread_wasm.js.symbols dosyasını içerir.

Sembolleri Google Play’e yükleme

Google Play’de kaydedilen çökmelerde sembolleri çözümlenmiş çağrı yığınlarının gösterilmesi için hata ayıklama sembollerini Google Play’e yükleyebilirsiniz. projecttitle.apk.symbols/lib/ dağıtım paketi çıktı klasörünün içeriğini zip arşivi olarak sıkıştırın. Bu klasör, arm64-v8a, armeabi-v7a ve x86_64 gibi mimari adlarını taşıyan bir veya daha fazla alt klasör içerir.

Android çağrı yığınına sembol çözümlemesi uygulama

1. Motoru derleme klasörünüzden alın

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

1. Zip arşivini bir klasöre çıkarın:

	$ unzip dmengine.apk -d dmengine_1_2_105

1. Çağrı yığınındaki adresi bulun

   Örneğin, sembolleri çözümlenmemiş çağrı yığınında şöyle görünebilir

   #00 pc 00257224 libmy_game_name.so

   Burada adres 00257224 değeridir

2. Adresi çözümleyin

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

Not: Android günlüklerinden bir yığın izi (stack trace) elde ederseniz, ndk-stack kullanarak buna sembol çözümlemesi uygulamanız mümkün olabilir

iOS çağrı yığınına sembol çözümlemesi uygulama

1. Yerel kod eklentileri kullanıyorsanız, sunucu sizin için sembolleri (.dSYM) sağlayabilir (bob.jar aracına --with-symbols seçeneğini geçirin)

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

1. Yerel kod eklentileri kullanmıyorsanız, standart motorun sembollerini indirin:

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

1. Yükleme adresini kullanarak sembol çözümlemesi uygulayın

   Bilinmeyen bir nedenle, yalnızca çağrı yığınındaki adresi girmek işe yaramaz (yani yükleme adresi 0x0 olduğunda)

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

# Yükleme adresini doğrudan belirtmek de işe yaramaz

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

Adrese yükleme adresini eklemek işe yarar:

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