Android: Enable native debug symbols generation by m4gr3d · Pull Request #105605 · godotengine/godot

m4gr3d · 2025-04-20T23:36:05Z

Enable native debug symbols generation for Android builds (template & editor)

The native debug symbols generation by gradle is controlled by the ndk.debugSymbolLevel property.
This PR sets that property to FULL, which causes both the debug info and symbol tables to be packaged. This results in a native debug symbols zip file which is about ~1G in size for all Android supported arches (arm32, arm64, x86_32, x86_64). The size of the symbols file can be brought down by setting the ndk.debugSymbolLevel property to symbol_table, which only packages the symbol tables.

Build-scripts counterpart PR - godotengine/godot-build-scripts#112

The build script PR can be used to see how to generate the debug symbols. Here a quick example for the arm64 arch:

scons platform=android arch=arm64 target=template_debug debug_symbols=yes generate_android_binaries=yes

Alongside generating the Android binaries, the inclusion of the debug_symbols=yes parameter will generate and output native debug symbols in the output bin directory.

The generated native debug symbols are stripped from the *.so libraries by gradle. To keep the debug symbols within the *.so packaged in the APK/AAB binaries, at the expense of binary size, the gradle_do_not_strip=yes parameter can be used.

scons platform=android arch=arm64 target=template_debug debug_symbols=yes generate_android_binaries=yes gradle_do_not_strip=yes

Note: The generate_apk scons parameter has been replaced by the generate_android_binaries parameter to reflect the fact the command generates APK, AAB, and AAR binaries. godotengine/godot-docs#10886 updates the documentation.

dsnopek · 2025-04-21T21:48:06Z

In my testing, using debug_symbols=yes generate_android_binaries=yes seems to work: the native symbols are generated in a separate ZIP file with the .dbg's inside.

However, adding do_not_strip_android_so=yes doesn't seem to be working. I would have expected that to leave the debug symbols embedded in the libgodot_android.so for use with local debugging, but I can tell by the file sizes that that's not the case.

My bin/libgodot.android.template_debug.arm64.so is 855M, but if I extract the android_sources.zip and the contained .aar file, the libgodot_android.so inside is only 73M.

syntaxerror247

Changes looks good and works in my testing.

debug_symbols=yes generate_android_binaries=yes correctly generate a native-debug-symbols.zip. Adding do_not_strip_android_so=yes also works as expected, generated android editor (arm64) apk size is 328.6 mb.

dsnopek · 2025-04-22T09:52:45Z

Adding do_not_strip_android_so=yes also works as expected, generated android editor (arm64) apk size is 328.6 mb.

Have you tested building export templates with do_not_strip_android_so=yes? That's what's not working for me, and I'd be curious if that's working for you as well. If so, then I guess I did something wrong? I didn't test using it with an editor build.

platform/android/detect.py

platform/android/java/editor/build.gradle

akien-mga · 2025-04-22T10:43:53Z

platform/android/java/build.gradle

-/**
- * Generates the same output as generateGodotTemplates but with dev symbols
- */
-task generateDevTemplate {
-    // add parameter to set symbols to true
-    project.ext.doNotStrip = "true"
-
-    gradle.startParameter.excludedTaskNames += templateExcludedBuildTask()
-    dependsOn = generateBuildTasks("template")
-
-    finalizedBy 'zipGradleBuild'
-}


Doesn't this removal mean that it's no longer possible to generate templates with debug symbols unless calling gradle from scons?

target=template_debug debug_symbols=yes generate_android_binaries=yes does the same thing.

Yes that's correct. Using scons, as @syntaxerror247 mentioned, will be the way to generate those templates.

This task also had the unforeseen side-effect of always enabling doNotStrip regardless of whether you were running it or not due to how gradle evaluates declared tasks.

akien-mga · 2025-04-22T10:56:03Z

I tested and can reproduce the issue pointed out by @dsnopek.

With:

scons p=android arch=arm64 target=template_debug debug_symbols=yes do_not_strip_android_so=yes generate_android_binaries=yes

I get:

$ lsmb bin
total 1994108
-rw-r--r--. 1 akien akien  242.33MB Apr 22 12:37 android_debug.apk
-rw-r--r--. 1 akien akien   23.14MB Apr 22 12:37 android_source.zip
-rw-r--r--. 1 akien akien   23.25MB Apr 22 12:37 godot-lib.template_debug.aar
-rwxr-xr-x. 1 akien akien  850.84MB Apr 22 12:36 libgodot.android.template_debug.arm64.so

Notably, there's no native-debug-symbols in platform/android/java/app/build/outputs/.

syntaxerror247 · 2025-04-22T12:08:09Z

Adding do_not_strip_android_so=yes also works as expected, generated android editor (arm64) apk size is 328.6 mb.

Have you tested building export templates with do_not_strip_android_so=yes? That's what's not working for me, and I'd be curious if that's working for you as well. If so, then I guess I did something wrong? I didn't test using it with an editor build.

I tried building the template and encountered the same issue. While the android_debug.apk is generated with debug symbols, the android_source.zip does not include them, so Gradle builds projects would not include debug symbols.

platform/android/java/lib/build.gradle

m4gr3d · 2025-04-22T15:55:38Z

Notably, there's no native-debug-symbols in platform/android/java/app/build/outputs/.

@akien-mga That's the intended behavior. When do_not_strip_android_so=yes is included, the native-debug-symbols file is not generated because the debug symbols are included in the so packaged in the apk. That's the reason why the android_debug.apk in your screenshot is 240+ Mb for a single arch, ~250Mb is the usual size for all arches when their so are stripped.

dsnopek

Thanks!

Building with target=template_debug generate_android_binaries=yes debug_symbols=yes gradle_do_not_strip=yes is working as expected for me now :-)

Repiteo · 2025-04-22T23:28:56Z

Thanks!

Summersay415 · 2025-04-23T00:13:33Z

Any reason to use do_not_strip_android_so instead of separate_debug_symbols? Right now the latter is only used on PC platforms

Alex2782 · 2025-04-23T00:52:46Z

I only found separate_debug_symbols here in the documentation. Android doesn't use this flag. sources

https://docs.godotengine.org/en/stable/contributing/development/compiling/introduction_to_the_buildsystem.html#debugging-symbols

When using debug_symbols=yes, you can also use separate_debug_symbols=yes to put debug information in a separate file with a .debug suffix. This allows distributing both files independently. Note that on Windows, when compiling with MSVC, debugging information is always written to a separate .pdb file regardless of separate_debug_symbols.

m4gr3d · 2025-04-23T01:12:21Z

Any reason to use do_not_strip_android_so instead of separate_debug_symbols? Right now the latter is only used on PC platforms

@Summersay415 I went with an Android specific parameter because I wanted to highlight that the debug symbols file generation is tied to the gradle build process, so if you were to run the command without including generate_android_binaries=yes, no debug symbols file would be generated.

That said, I don't have objections with using separate_debug_symbols instead if we think that'd be more consistent.

m4gr3d · 2025-04-23T01:46:32Z

@Summersay415 I've opened #105671 to discuss which parameter to use.

Kimau · 2025-05-15T10:34:37Z

Having just lost a bunch of time to this PR yesterday because I updated and a bunch of automated scripts broke I'm shocked that
generate_apk was generate_android_binaries changed with no noticeable benefit.

I understand its a slightly better name but there needs to be a higher bar to be met for renaming things. It makes cherry picking much harder and in cases like this can break existing workflows and cost users time and money.

akien-mga · 2025-05-15T10:41:35Z

In such case we could (should) use an alias to preserve support for previous names if they're still doing roughly the same thing.

Edit: Done: #106435.

Alex2782 · 2025-05-15T13:18:18Z

I've been using both parameters for about a month, necessary to switch between different PRs and to test them.

generate_apk=true generate_android_binaries=true

m4gr3d added bug enhancement platform:android topic:buildsystem cherrypick:4.4 Considered for cherry-picking into a future 4.4.x release labels Apr 20, 2025

m4gr3d added this to the 4.5 milestone Apr 20, 2025

m4gr3d requested a review from a team as a code owner April 20, 2025 23:36

m4gr3d mentioned this pull request Apr 20, 2025

Setup Android debug symbols godotengine/godot-build-scripts#112

Merged

m4gr3d force-pushed the setup_debug_symbols branch from c29cfac to 087acb6 Compare April 21, 2025 14:35

m4gr3d requested a review from a team as a code owner April 21, 2025 14:35

m4gr3d mentioned this pull request Apr 21, 2025

Update the Android build documentation godotengine/godot-docs#10886

Merged

syntaxerror247 reviewed Apr 22, 2025

View reviewed changes

akien-mga reviewed Apr 22, 2025

View reviewed changes

platform/android/detect.py Outdated Show resolved Hide resolved

akien-mga reviewed Apr 22, 2025

View reviewed changes

platform/android/java/editor/build.gradle Show resolved Hide resolved

akien-mga reviewed Apr 22, 2025

View reviewed changes

syntaxerror247 reviewed Apr 22, 2025

View reviewed changes

platform/android/java/lib/build.gradle Show resolved Hide resolved

Enable native debug symbols generation

8a514ae

m4gr3d force-pushed the setup_debug_symbols branch from 087acb6 to 8a514ae Compare April 22, 2025 16:04

syntaxerror247 approved these changes Apr 22, 2025

View reviewed changes

dsnopek approved these changes Apr 22, 2025

View reviewed changes

akien-mga changed the title ~~Enable native debug symbols generation~~ Android: Enable native debug symbols generation Apr 22, 2025

Repiteo merged commit 34cb899 into godotengine:master Apr 22, 2025
20 checks passed

m4gr3d deleted the setup_debug_symbols branch April 23, 2025 01:12

m4gr3d mentioned this pull request Apr 23, 2025

Use separate_debug_symbols to control generation of the separate Android debug symbols file #105671

Merged

akien-mga mentioned this pull request May 15, 2025

Android: Re-add generate_apk alias for compatibility #106435

Merged

m4gr3d removed the cherrypick:4.4 Considered for cherry-picking into a future 4.4.x release label Jun 26, 2025

m4gr3d mentioned this pull request Jun 26, 2025

Android: Fix the build logic to generate the native debug symbols #107998

Merged

Uh oh!

Conversation

m4gr3d commented Apr 20, 2025 • edited by syntaxerror247 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dsnopek commented Apr 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

syntaxerror247 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dsnopek commented Apr 22, 2025

Uh oh!

Uh oh!

Uh oh!

akien-mga Apr 22, 2025

Choose a reason for hiding this comment

Uh oh!

syntaxerror247 Apr 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

m4gr3d Apr 22, 2025

Choose a reason for hiding this comment

Uh oh!

akien-mga commented Apr 22, 2025

Uh oh!

syntaxerror247 commented Apr 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

m4gr3d commented Apr 22, 2025

Uh oh!

dsnopek left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Repiteo commented Apr 22, 2025

Uh oh!

Summersay415 commented Apr 23, 2025

Uh oh!

Alex2782 commented Apr 23, 2025

Uh oh!

m4gr3d commented Apr 23, 2025

Uh oh!

m4gr3d commented Apr 23, 2025

Uh oh!

Kimau commented May 15, 2025

Uh oh!

akien-mga commented May 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Alex2782 commented May 15, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

m4gr3d commented Apr 20, 2025 •

edited by syntaxerror247

Loading

dsnopek commented Apr 21, 2025 •

edited

Loading

syntaxerror247 left a comment •

edited

Loading

syntaxerror247 Apr 22, 2025 •

edited

Loading

syntaxerror247 commented Apr 22, 2025 •

edited

Loading

akien-mga commented May 15, 2025 •

edited

Loading