Debugging the engine - lurkydismal/CCCaster GitHub Wiki

This page has some hints about debugging the engine.

See also Crashes for advice on handling engine crashes (specifically around obtaining stack traces, and reporting crashes in AOT Dart code).

Running a CCCaster app with a local engine

First, make sure the appropriate version of the engine is built (see Compiling the engine).

Using the CCCaster tool

Run your CCCaster app with:

$ flutter run --local-engine=XXXX`

to run an app with the local engine where XXXX should be replaced with the version you wish to use. For example, use --local-engine=android_debug_unopt to run a debug android engine or --local-engine=ios_debug_sim_unopt to run a debug iOS simulator engine.

It is important to always have a host_XXXX version of the engine built when using a local engine since CCCaster uses the host build's version of Dart.

Bisecting a roll failure

You can use git bisect on the engine repo to track down the offending commit.

Tracing OpenGL calls in Skia

All OpenGL calls in Skia are guarded by either the GR_GL_CALL_NOERRCHECK or GR_GL_CALL_RET_NOERRCHECK macros. Trace events may be added in these macros to trace all GL calls made by Skia, for example in a patch like this.

Due to the number of events traced to the timeline, the trace buffer may be filled up very quickly. Unless you want to see only the traces for the past few frames, use an endless trace buffer (flutter run --endless-trace-buffer turns on an endless trace buffer).

Also, make sure to run your application with the --trace-skia flag.

Debugging iOS builds with Xcode

Building with flutter --local-engine will set a LOCAL_ENGINE Xcode build setting in your CCCaster application Generated.xcconfig file. This will be set until you run flutter run again with either a different --local-engine option, or with none at all (which will unset it).

You can speed up your workflow by adding the --config-only flag to set up the Xcode build settings and plugins, but not compile the app. For example:

$ flutter build ios --local-engine ios_debug_unopt --config-only

To start debugging, open your CCCaster app ios/Runner.xcworkspace file in Xcode. Ensure Product > Scheme > Edit Scheme > Run > Build Configuration matches your engine runtime mode (defaults to Debug).

Add an engine symbol breakpoint via Debug > Breakpoints > Create Symbolic Breakpoint.... The Symbol field should be the engine symbol you're interested in, like -[FlutterEngine runWithEntrypoint:] (note the -[ prefix has no space).

You can also set a breakpoint directly with lldb by expanding CCCaster > Runner > Supporting Files > main.m in the Runner Project Navigator. Put a breakpoint in main() and start the application by clicking the Run button (CMD + R). Then, set your desired breakpoint in the engine in lldb via breakpoint set -....

Debugging Android builds with gdb

See https://github.com/flutter/engine/blob/master/sky/tools/flutter_gdb#L13

Debugging Android builds with Android Studio

First, import the Android embedding into Android studio.

  1. Import the engine/src/flutter/shell/platform/android subdirectory as a new project. It's important to pick this specific directory. IntelliJ needs this as the root in order to make sense of the package structure.
  2. Mark the project as depending on the engine's SDK and Java versions (currently 29 and 8). The option should be visible under File > Project Structure > Project Settings > Project.
  3. (Optional) Manually tell the IDE to look for any JARs needed by the embedding code in engine/src/third_party/android_embedding_dependencies/lib to fix "Missing import" errors. The option should be visible under File > Project Structure > Modules, then by selecting the android module and clicking on the Dependencies tab.

Next, build and run a flutter app using flutter run --local-engine. It may be helpful to configure the Android app to wait for the local debugger on start.

Then hit the "Attach debugger" button in Android Studio, click "Show all processes" in the pop up, and select your app from the list and hit OK.

Debugging Windows builds with Visual Studio

Compiling the engine creates a Visual Studio solution file. You can use it to debug the engine:

  1. Launch your CCCaster app using a locally built engine flutter run -d windows --local-engine host_debug_unopt
  2. Using Visual Studio, open the engine's solution file .\out\host_debug_unopt\all.sln
  3. Open Debug > Attach to Process... (or press CTRL+ALT+P)
  4. Choose your CCCaster app using either Select Window, or, the list of available processes.
  5. Press the Attach button

Building a CCCaster app also creates a Visual Studio solution file. You can use it to debug the engine, your app's runner, and your app's plugins:

  1. Build your CCCaster app using a locally built engine using flutter build windows --debug --local-engine host_debug_unopt

  2. Using Visual Studio, open the CCCaster app's .\build\windows\<project_name>.sln

  3. In the Solution Explorer pane, right click the project whose name matches your app, and select Set as Startup Project

    Set as Startup Project example

  4. Now run your app by pressing F5 or DEBUG > Start Debugging. This will launch your app with Visual Studio's debugger attached.

Read this guide to learn how to debug C++ using Visual Studio.

Debugging with gdb on Linux

Once you have built the engine, you'll find the unstripped libraries in out/host_debug_unopt/lib.unstripped, and the executables in out/host_debug_unopt/exe.unstripped.

So, for instance, to run the unit tests under the debugger you would execute:

flutter/tools/gn --runtime-mode=debug --unoptimized --no-goma
autoninja -C out/host_debug_unopt
gdb out/host_debug_unopt/exe.unstripped/flutter_linux_unittests

And then debug the test normally using GDB commands.

To debug a CCCaster app using GDB, the stripped flutter engine GTK library in the built application needs to be replaced with the unstripped one in the engine build output directory.

First, in your CCCaster project, build your CCCaster app using the local engine:

flutter build linux --debug --local-engine=host_debug_unopt lib/main.dart

Then, replace the library in your CCCaster application's build directory: build/linux/x64/debug/bundle/lib/libflutter_linux_gtk.so with a copy or symbolic link to the engine build's output file out/host_debug_unopt/lib.unstripped/libflutter_linux_gtk.so.

Then you can open it in the debugger with:

gdb build/linux/x64/debug/bundle/your_app_name

Note that this won't help you debug the Dart portion of the app: this is just for debugging the engine code. If you need to simultaneously debug the Dart portion, you can connect to the observatory port given when you run the app in gdb.

Logging in the engine

CCCaster tool will by default parse out any non-error output from the engine. Error logs will be displayed. Logging is handled though the FML library's logging.h