Let's say your app is misbehaving because of a Flutter engine bug. Let's debug that!
Let's open your app using Visual Studio:
-
Run
flutter build windows
to ensure Flutter has generated a Visual Studio project for your app. -
Open
./build/windows/ALL_BUILD.vcxproj
in Visual Studio. This project builds the native entry point for your Flutter app. -
In the
Solution Explorer
, right click on the project whose name matches your app, and selectSet as Startup Project
.In the screenshot above, my app is called
debug_example
. Your app will likely have a different name! -
Now run your app by pressing
F5
orDEBUG
>Start Debugging
. This should start your app with Visual Studio's debugger attached.
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).
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
.
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 youflutter upgrade
or change channels usingflutter channel
. You will need to repeat the steps above whenever the SDK's engine changes.
Let's tell Visual Studio where it can find the engine's symbols:
-
Open the Debugging options using
DEBUG
>Options...
. -
Make sure that
Enable Just My Code
is unchecked:This allows the Visual Studio debugger to step into external code, like the Flutter engine.
-
Navigate to the
Symbols
pane and use the+
button to add<Flutter SDK path>/bin/cache/artifacts/engine/windows-x64
as a symbol location: -
Close the
Options
window
Now, let's actually load the engine's symbols:
-
Open the
Modules
window usingDEBUG
>Windows
>Modules
(orCtrl+Alt+U
): -
In the
Modules
window, right click theflutter_windows.dll
item and selectLoad Symbols
: -
The engine's symbols should now be loaded:
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 clone
d earlier and press Open
. You should now be able to debug into the Flutter engine's source code!
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 codeio.flutter.raster
- Runs the Flutter engine's rasterizerio.flutter.io
andio.flutter.worker.*
- Runs IO tasks