Quick tutorial on debugging the MIEngine

This wiki page will give a quick overview on how you can get started digging into the source code of the MIEngine in Visual Studio scenarios (NOT Visual Studio Code). In this tutorial, we are going to debug a project in WSL. If you are interested in modifying the MIEngine to target some other platform, this tutorial is still probably useful to you so that you can see how to quickly test your code for the WSL scenario.

Setup steps:

1. Follow the instruction in building the MIEngine to install Visual Studio and build this repo. Note that this tutorial requrise the "Linux and embedded development with C++" workload.

2. If you haven't already done so, clone the MIEngine repository.

3. Setup WSL

   • Enable the WSL feature in Windows. See https://aka.ms/wslinstall for instructions.
   • Open the Microsoft Store, and download a Linux distribution, such as 'Ubuntu'.
   • Setup your WSL instance by ensuring that a compiler, linker and GDB are installed. See learn.microsoft.com for instructions.

4. If you didn't already do this for building MI Engine, this tutorial requires installing the "Linux, Mac, and embedded development with C++" Workload in Visual Studio

Update Microsoft.MIDebugPackage.pkgdef

The version of MIEngine that ships with Visual Studio will keep your new version from loading, so we need to tweak it so that your version is used.

1. Open a developer command prompt as an Administrator
2. cd /d "%VSINSTALLDIR%\Common7\IDE\CommonExtensions\Microsoft\MDD\Debugger"
3. notepad Microsoft.MIDebugPackage.pkgdef
4. Locate the following lines:

[$RootKey$\BindingPaths\{7A28CEDA-DA3E-4172-B19A-BB9C810046A6}]
"$PackageFolder$"=""

5. Comment those lines out by adding a ; in front of the lines like below:

; [$RootKey$\BindingPaths\{7A28CEDA-DA3E-4172-B19A-BB9C810046A6}]
; "$PackageFolder$"=""

6. Open a non-admin Developer Command Prompt and run devenv.com /updateConfiguration.

Steps:

1. Start your main instance of Visual Studio, and open <MIEngine-Repo-Root>\src\MIDebugEngine.sln.

2. Ensure that MIDebugPackage project is set as the startup project.

   • Open Solution Explorer
   • Find the 'MIDebugPackage' in the list of projects
   • Right click, and invoke 'Set as Startup Project'

3. In solution explorer, find the MIDebugEngine project, and open Engine.Impl\DebuggedProcess.cs.

4. Find the Initialize method of the class and set a breakpoint.

5. Hit F5 to start debugging. This will build the project and launch an experimental instance of Visual Studio.

6. In The experimental instance:

   • Click the button to create a new project
   • Set the filter to language filter to 'C++' and the platform to 'Linux'
   • Select the 'CMake Project' template, then set a project directory and invoke create
   • There is a "Target System" toolbar dropdown that will say "Local Machine", change that to your WSL instance
   • Open main.cpp from the created project
   • Set a breakpoint in the main method.
   • F5 or Debug -> Start Debugging to start debugging.

7. Your breakpoint in DebuggedProcess.Initialize will hit. You can step through and see the commands that are being sent to GDB if you like. If you open the output window in your main Visual Studio instance, you can also see all the commands that we sent and the response/events that came back.

8. Hit F5 from this breakpoint and see your experimental instance stop at a breakpoint as well.