How to debug the Flutter engine on Windows

tutorial.md

How to debug the Flutter engine on Windows

Let's say your app is misbehaving because of a Flutter engine bug. Let's debug that!

Use Visual Studio to run your app

Let's open your app using Visual Studio:

1. Run flutter build windows to ensure Flutter has generated a Visual Studio project for your app.

2. Open ./build/windows/ALL_BUILD.vcxproj in Visual Studio. This project builds the native entry point for your Flutter app.

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

   

   In the screenshot above, my app is called debug_example. Your app will likely have a different name!

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

Configure Visual Studio's debugger

We need to provide Visual Studio with both the Flutter engine's source code and the engine's symbols (which maps the compiled native code back to source code).

Find your Flutter installation information

First, find your Flutter SDK path and Flutter engine revision using the terminal: flutter doctor --verbose.

Let's say I have the following output:

PS C:\> flutter doctor --verbose
[✓] Flutter (Channel stable, 3.7.0, on Microsoft Windows [Version 10.0.22621.1105], locale en-US)
    • Flutter version 3.7.0 on channel stable at C:\Code\f\flutter
    • Upstream repository https://github.com/flutter/flutter.git
    • Framework revision b06b8b2710 (5 days ago), 2023-01-23 16:55:55 -0800
    • Engine revision b24591ed32
    • Dart version 2.19.0
    • DevTools version 2.20.1

...

My Flutter SDK path is C:\Code\f\flutter and my Flutter engine revision is b24591ed32.

Get the Flutter engine's source code

In the terminal, use Git to download the Flutter engine source code: git clone https://github.com/flutter/engine.

Enter the Flutter engine's directory using cd engine. This is your Flutter engine path.

Now, switch to your Flutter SDK's version of the engine: git checkout <Flutter engine revision>

Note ⚠️ The Flutter SDK's engine changes whenever you flutter upgrade or change channels using flutter channel. You will need to repeat the steps above whenever the SDK's engine changes.

Load the engine's symbols

Let's tell Visual Studio where it can find the engine's symbols:

1. Open the Debugging options using DEBUG > Options....

2. Make sure that Enable Just My Code is unchecked:

   

   This allows the Visual Studio debugger to step into external code, like the Flutter engine.

3. Navigate to the Symbols pane and use the + button to add <Flutter SDK path>/bin/cache/artifacts/engine/windows-x64 as a symbol location:

   

4. Close the Options window

Now, let's actually load the engine's symbols:

1. Open the Modules window using DEBUG > Windows > Modules (or Ctrl+Alt+U):

   

2. In the Modules window, right click the flutter_windows.dll item and select Load Symbols:

   

3. The engine's symbols should now be loaded:

   

Debug!

Pause the app if it isn't already using Break all (or Ctrl+Alt+Break). In the Call Stack section, you should see a list of method calls. Methods with the flutter_windows.dll! prefix are part of the Flutter engine:

Double-click on one of these methods. Visual Studio will open a File Explorer popup and ask for the source code location:

In this File Explorer popup, navigate to the the Flutter engine path you git cloned earlier and press Open. You should now be able to debug into the Flutter engine's source code!

Flutter engine's threads

The Flutter engine uses multiple threads. You can switch between these using the Thread dropdown:

The most useful threads include:

• Main thread - Runs the app's entry point, Windows embedder, plugins, etc...
• io.flutter.ui - Runs Dart code
• io.flutter.raster - Runs the Flutter engine's rasterizer
• io.flutter.io and io.flutter.worker.* - Runs IO tasks

Additional resources

1. Learn to debug C++ using Visual Studio
2. Debugging External Sources with Visual Studio
3. Specify symbol and source files in the debugger