MIEngine: driving gdb and lldb from Visual Studio

A debug engine that speaks Machine Interface

MIEngine is a Visual Studio extension that enables debugging with debuggers that support the gdb Machine Interface specification, and the README names GDB and LLDB as the examples.

The two halves of that sentence describe two different protocols. On the Visual Studio side there is the Core Debug Interfaces, the family of IDebug interfaces that the Visual Studio user interface drives. On the other side there is Machine Interface, which the README describes as a text based protocol developed by GDB that allows a debugger to be used as a separate component of a larger system.

That second property is the reason the project exists at all. A native Windows debugger runs inside the process it debugs. MIEngine does not. It is a translation layer: your Visual Studio session sends debugger commands to the MIEngine process, MIEngine translates them into Machine Interface text, a gdb or lldb instance on the other end executes them, and the answers travel back the same way. That is what allows a program running on a Raspberry Pi to be debugged from a Windows workstation.

The project is written in C#, it is hosted on GitHub under the Microsoft organisation, and it is MIT licensed. The README links further background on Visual Studio debugger extensibility and on GDB's Machine Interface for anyone who wants the protocol details.

The same engine underpins cppdbg in VS Code

The part of the repository that matters most for anyone outside Visual Studio is OpenDebugAD7, described as an adaptation layer between the Debug Adapter Protocol and debug engines, and stated to be what allows MIEngine to be used with Visual Studio Code.

The distinction between the two interfaces is worth stating clearly. A Visual Studio debug engine implements the IDebug interfaces and is loaded by Visual Studio itself. A VS Code debug adapter implements the Debug Adapter Protocol, a JSON based protocol over a standard input and output pipe, and VS Code launches it as a separate process. OpenDebugAD7 sits between that protocol and the engine, so a single implementation can serve both hosts.

The payoff is already shipped in a product most C++ developers use. The README states that in Visual Studio Code, MIEngine powers the cppdbg debug adapter, which is part of the C/C++ extension. In other words, if you debug a Linux binary from VS Code with the Microsoft C/C++ extension, you are already running this engine, whether or not you know it.

That also frames the project's relationship to its own releases. The repository tags include VS Code C/C++ Extension versions and Visual Studio preview versions, because the engine ships inside those products and the tags mark the points where it was integrated. The repository publishes OpenDebugAD7 separately too, with a shell script for publishing it in the root.

SSHDebugPS and debugging a remote Linux process

The second component in the repository is SSHDebugPS, a Visual Studio Port Supplier that lets Visual Studio attach to processes over SSH or in Linux Docker, and which the README says could easily be extended to any other executable that provides a shell into a Linux container or machine.

A port supplier is the Visual Studio mechanism for describing where a debug target lives and how to reach it. In the native Windows case that is a machine and a port. The SSH supplier takes the same idea and points it at a remote host reached over an SSH connection, which is the piece that makes a Linux container or a virtual machine debuggable from a Windows desktop with the normal Visual Studio UI.

The framing in the README is careful: this is not a hard coded list of supported environments but an abstraction that can be extended to any executable providing a shell into a Linux container or machine. In practice that means a container runtime that offers an exec style shell, or a custom script that wraps one, can be plugged in without touching the engine.

The repository root shows the packaging side: a MIEngine.UnixPortSupplier.nuspec file for that component, a MIEngine.mdd.nuspec for the debug engine itself, and a PublishOpenDebugAD7.sh script for the adapter.

Which platforms it can still reach

The platform section of the README has shrunk over the years, and the shrinking is documented rather than hidden.

Debugging C and C++ on Android is still supported, with a link to an article on debugging JNI applications from Visual Studio. iOS support is struck through, and the note says plainly that it is not available after Visual Studio 2022.

Beyond that the rule is simply anything that supports GDB. The README puts it as debugging on any platform that supports GDB, such as Linux and even the Raspberry Pi, with a link to an article on debugging C code on Linux from Visual Studio.

The Raspberry Pi example is the one that explains the design. A board running Linux has a gdb on it, and the board is reachable over the network. Nothing about MIEngine requires a Windows target, because the actual debugger is a Linux process that MIEngine drives over a text protocol. The Visual Studio side is just a front end.

The practical consequence for an adopter is that the constraint is the debugger on the target, not the operating system of the workstation. If the machine where the code runs has a gdb or an lldb that speaks MI, MIEngine has something to talk to.

Building it: Visual Studio or the .NET CLI

The build section of the README is brief because the detail lives elsewhere. MIEngine can be built with either Visual Studio or with the .NET CLI, and the README sends you to the project wiki for more information.

The repository layout suggests both paths are real. There is a build directory, an eng directory for engineering scripts, a tools directory, a .config directory, which is where the .NET tools manifest usually lives, and a .devcontainer directory for a reproducible development environment. The loc directory points at localisation resources, and the docs and test directories hold the documentation and the test suite. There are also IL and Keys directories, and a ThirdPartyNotices.txt with DependencyLicenses and PackageLicenses folders beside it, which is the packaging equivalent of an attribution file.

The SECURITY.md file at the root is the channel for reporting a vulnerability in the component, and the contributor process is documented on the wiki, with a Contributing-Code page that the README asks you to read before sending a pull request. The README also invites new contributors to browse the open and closed pull requests and the issue list, and to start a discussion by filing an issue or a gist.

The project has adopted the Microsoft Open Source Code of Conduct, with a link to the code of conduct FAQ and an [email protected] address for questions about it.

Releases, licence and how this compares to debugging natively

The release tags are where the project looks unusual, and it is worth reading them carefully. The three most recent are VS Code C/C++ Extension 1.19.6, Visual Studio 2022 17.12 Preview 3, and Visual Studio 2022 17.10 Preview 3, all dated 2024-10-03. The last push to the repository was on 2026-10-15.

So the tags do not track MIEngine releases on their own. They mark the points at which a build of the engine was shipped inside the Visual Studio and VS Code products, and MIEngine has no independent version stream of its own in those tags. If you consume the engine directly rather than through one of those products, you are building from the main branch rather than pinning a tagged release, and the wiki is where the supported consumption paths are described.

The licence is the MIT License, with the text in License.txt at the root of the repository.

The alternative to all of this is to skip the Visual Studio layer. You can debug a Linux target with lldb or gdb directly, or attach VS Code to the cppdbg adapter, which embeds this engine and gives you the same MI translation without a separate Visual Studio installation. The difference in approach is that MIEngine exists to give you the Visual Studio experience, with its breakpoints, call stack, watch windows and multi target debugging, while pointing at a machine that is not your workstation. If you are comfortable in a terminal debugger, the extra layer buys you a UI rather than a capability.

Editorial conclusion

MIEngine is the component you want when a team debugs C and C++ on Linux, on a Raspberry Pi, in a container or over SSH but lives in a Visual Studio workflow, because it puts the familiar debugger interface on top of a debugger that runs next to the target. It is the wrong choice for a team already standardised on VS Code with the cppdbg adapter, since that adapter already embeds this engine, and it is a poor fit for platforms without a Machine Interface capable debugger. Verify first that the debugger on the target speaks the MI version MIEngine expects, read the wiki for the build steps since the README keeps them there, and check the licence and third party notice files in the root before you redistribute a built extension.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. microsoft/MIEngine on GitHub
4. README
5. Releases