Musa.Runtime - Universal C++ RunTime Library

June 6, 2026 · View on GitHub

English · 简体中文
📖 Architecture · Developer Guide · Build System · Overlay Diff Report

Overview

Musa.Runtime is a Microsoft MSVC runtime library adapted for Windows kernel-mode development. Built on Musa.Core, it carries forward the architecture pioneered by ucxxrt.

Core goal: Give kernel developers the same C++ experience that application developers enjoy.

Design highlight: Inspired by Docker's layered filesystem, Musa.Runtime uses an overlay mechanism to selectively replace files on top of the original MSVC SDK source — no fork, no independent copy to maintain. See Architecture for details.

Quick Start

1. Install

NuGet (recommended):

<ItemGroup>
  <PackageReference Include="Musa.Runtime">
    <Version>1451.28000.0</Version>
  </PackageReference>
</ItemGroup>

Or right-click your project → Manage NuGet Packages → search Musa.Runtime → Install.

Manual import: Download from Releases and unzip:

<PropertyGroup>
  <MusaRuntimeOnlyHeader>false</MusaRuntimeOnlyHeader>
</PropertyGroup>
<Import Project="..\Musa.Runtime\config\Musa.Runtime.Config.props" />
<Import Project="..\Musa.Runtime\config\Musa.Runtime.Config.targets" />
<!-- place above Microsoft.Cpp.targets -->

2. Rename `DriverEntry` → `DriverMain`

Musa.Runtime provides its own DriverEntry (which handles CRT initialization). Your driver entry point must be renamed to DriverMain:

EXTERN_C NTSTATUS DriverMain(PDRIVER_OBJECT DriverObject, PUNICODE_STRING RegistryPath)
{
    DriverObject->DriverUnload = [](auto obj) { MusaLOG("Unload."); };
    // Your code here
    return STATUS_SUCCESS;
}

3. Use C++ in Kernel

#include <vector>
#include <string>
#include "kext/kallocator.h"

void Example()
{
    std::vector<std::string, kallocator<std::string>> vec;
    vec.push_back("hello from kernel");
}

⚠️ kallocator defaults to PagedPool. When used at DISPATCH_LEVEL or above, specify NonPagedPool explicitly.

Features

Feature	Status	Notes
x64	✅	Primary platform
ARM64	⚠️	Experimental
New / Delete	✅	Backed by `ExAllocatePoolWithTag`
C++ Exception (`/EHa`, `/EHsc`)	✅	IRQL ≤ APC_LEVEL
Static Object Construction	✅	Runs at driver load time
SAFESEH / GS	✅	Buffer security check
SEH (`__try`/`__except`)	✅	Access violation, finally, continue search
STL Containers / Algorithms	✅	Full OneCore / CoreCRT support
`std::format` / `std::print`	✅	C++23 formatted output
`std::regex`	✅	Full regular expression support
`std::filesystem`	✅	C++17 filesystem (Phase 1)
String Conversions (`std::stoi`/`stod`/etc.)	✅	stoi, stol, stoul, stoll, stoull, stod, stof
`thread_local`	❌	Compiler-level limitation (fs/gs register access)

Documentation

Document	Content
📐 Architecture	Design philosophy (overlay pattern), component architecture, kernel-mode adaptations
📝 Developer Guide	Installation, STL usage, exception handling, kallocator, troubleshooting
🔧 Build System	Project structure, build process, version management, publish pipeline
🔬 Overlay Diff Report	Per-file differential analysis of all overlay files

Build from Source

> git clone --recurse-submodules https://github.com/MiroKaku/Musa.Runtime.git
> cd Musa.Runtime
> .\BuildAllTargets.cmd

Prerequisites: Visual Studio 2026 (latest) + WDK