Debugging Android runtime issues

Enable verbose runtime logging

If a net6.0-android (or later) C# project is available, adding the following:

 <ItemGroup>
   <AndroidEnvironment Include="AndroidEnv.txt" />
 </ItemGroup>

with AndroidEnv.txt:

debug.mono.log=mono_log_level=debug,mono_log_mask=all
MONO_SDB_ENV_OPTIONS=loglevel=10    # only needed if you're debugging the managed debugger

Will enable additional Mono runtime logging in the adb log. This is often enough to diagnose issues such as missing assemblies or other loader problems.

Managed Debugging

Should work from Visual Studio (Windows)

Native debugging

Install Android Studio.

Download the symbols nupkg corresponding to the runtime pack that is used by the app. The runtime pack for the android workload is in a folder like ${DOTNET_ROOT}/packs/Microsoft.NETCore.App.Runtime.Mono.android-x86/6.0.0-rc.1.21451.13

The symbols are in a package called Microsoft.NETCore.App.Runtime.Mono.android-x86.6.0.0-rc.1.21451.13.symbols.nupkg uploaded to (FIXME: where does the symbols nuget go?). Extract it to some folder using unzip and in the runtimes/android-x86/native/ folder rename the *.so.dbg files to *.so.so (we will need to add the symbols files to Android Studio, but its file picker only shows *.so extensions)

1. Build the APK normally using dotnet build, (this will produce a AppName-Signed.apk in the output folder)
2. Start an Android emultator
3. Install the app on the emulator using dotnet build -t:Install
4. Open the APK in Android Studio with "Profile or Debug APK"
5. In the "Project" viewer, choose the "cpp" folder, then libmonosgen-2.0.so then double-click libmonosgen-2.0.so inside the libmonosgen-2.0.so folder.
6. In the "Debug Symbols" view click "Add", navigate to the extracted runtime symbols nuget and select libmonosgen-2.0.so.so
7. In the "Path Mappings" section, select the toplevel folder and add a Local Path to a git checkout of the release/6.0 tree corresponding to the nuget. Click Apply Changes.
8. Start an emulator or connect to a device
9. On the menu bar select "Run > Edit Configurations..." and on the "Debugger" tab make sure the "Debug Type" is something other than "Java Only"
10. Start debugging.
11. You should now have function names, local variables, as well as stepping through the runtime C code.

Since you're debugging an optimized release build, it is likely the debugger will not be able to materialize every local variable.

Native debugging using a local debug build of Mono

Ensure the prerequisites are met for Testing Android.

Build the runtime for your android architecture <ANDROID_ARCH> and keep debug symbols in the binary:

./build.sh -s mono+libs -os android -arch <ANDROID_ARCH> -c Debug /p:KeepNativeSymbols=true

In the source code for the C# project, add the following to the .csproj (replacing <RUNTIME_GIT_ROOT> by the appropriate location and <ANDROID_ARCH> with the built android architecture):

  <Target Name="UpdateRuntimePack"
            AfterTargets="ResolveFrameworkReferences">
      <ItemGroup>
        <ResolvedRuntimePack PackageDirectory="<RUNTIME_GIT_ROOT>/artifacts/bin/microsoft.netcore.app.runtime.android-<ANDROID_ARCH>/Debug"
                             Condition="'%(ResolvedRuntimePack.FrameworkName)' == 'Microsoft.NETCore.App'" />
      </ItemGroup>
  </Target>

Then rebuild and reinstall the project, open the apk in Android Studio (File > Profile or Debug APK), and debug.

Note: If debugging in Android Studio stops at signals SIGPWR and SIGXCPU during startup, configure LLDB to not stop the process for those signals via process handle -p true -s false -n true SIGPWR and process handle -p true -s false -n true SIGXCPU in Android Studio's LLDB tab.

Native and managed debugging or debugging the managed debugger

This workflow is useful to look for issues in the debugger itself, or to debug using a mixture of C and C# debugging.

Install sdb.

Start sdb and set it to listen listen 127.0.0.1 5000 (the port number is up to you).

Run the following adb command to set Mono apps to connect to a debugger on startup:

$ adb shell setprop debug.mono.extra "debug=10.0.2.2:5000,loglevel=10"

(loglevel=10 will produce debugger protocol messages in the adb log. If you're not debugging the debugger it can be omitted. For other debugger options see print_usage() in src/mono/mono/component/debugger-agent.c)

Now launch the app from Android Studio. It should run and connect to the debugger.