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 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 22.04 LTS'.
   • Setup your WSL instance by ensuring that a compiler, linker and GDB are installed. For example, on Ubuntu you do this with sudo apt-get update and sudo apt-get install build-essential gdb.
   • Ensure that an SSH server is installed and running. Example setup for Ubuntu:
     • Install it with sudo apt-get install openssh-server.
     • Configure the port number by editing /etc/ssh/sshd_config. You likely want a high number such as '2022' to avoid conflicts. Example: sudo nano /etc/ssh/sshd_config, find the port setting and configure it.
     • Configure authentication by either setting up a pair of SSH keys, or by commenting out PasswordAuthentication no in sshd_config
     • Start ssh with sudo service ssh start

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 'C++' and find a 'Console Application'
   • Create the project. Your non-experimental Visual Studio instance may stop on an exception while this is happening. If so, ignore it.
   • Open Tools->Options
   • Find the 'Cross Platform' options and add an entry to connect to your WSL instance. You want a 'Host name' of 'localhost', set the 'Port' to whatever you configured in your WSL instance.
   • Open main.cpp from the created project.pkg
   • 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.