Ahwoo.BRUTAL.Interop 2026.10.1

Brutal Interop

C/C++ parsing, AST representation, and layered interop code generation for the BRUTAL framework.

• Platform Support
• Links
• For Users
  • Prerequisites
  • Installation
  • Usage
• For Developers
  • Prerequisites
  • Compilation and Testing
  • Contributing

Brutal Interop provides the tools to parse C/C++ headers and generate managed ↔ native interop in a series of composable transformation steps. At the centre is Brutal.Ast: a language-neutral intermediate representation that models namespaces, types, fields, methods, expressions, and statements independently of any source language or output target. Brutal.Ast.CppAst populates that representation from C/C++ headers via libclang, and from there the AST can be walked and reshaped through as many stages as needed — for example, generating a C extern wrapper, then a C# PInvoke layer, then a user-facing C# API. Brutal.Interop provides the runtime handle and marshalling types consumed by generated code, while Brutal.Interop.NativeBuild integrates the CMake build of native libraries into the .NET build and pack pipeline.

Platform Support

• Windows (x64)
• Linux (x64)
• macOS (Apple Silicon)

Links

• GitHub
• BRUTAL Docs

NuGet Packages

• RocketWerkz.Brutal.Ast - Language-neutral AST: declarations, types, expressions, statements, and tree traversal
• RocketWerkz.Brutal.Ast.CppAst - C/C++ header parser that produces a Brutal.Ast compilation unit via libclang
• RocketWerkz.Brutal.Ast.SourceGenerators - Roslyn analyzer that generates ISyntax node boilerplate; bundled with RocketWerkz.Brutal.Ast
• Ahwoo.BRUTAL.Interop - Runtime interop handle attributes and UTF-8 string marshalling types
• RocketWerkz.Brutal.Interop.SourceGenerators - Roslyn analyzer that generates handle marshalling code; bundled with Ahwoo.BRUTAL.Interop
• RocketWerkz.Brutal.Interop.NativeBuild - MSBuild targets and CMake tooling that build and package native libraries as part of the .NET pipeline

For Users

Prerequisites

• .NET SDK (version 10.0 or later)

Installation

To install the packages via NuGet, run the following commands in your project directory:

dotnet add package RocketWerkz.Brutal.Ast
dotnet add package RocketWerkz.Brutal.Ast.CppAst
dotnet add package Ahwoo.BRUTAL.Interop
dotnet add package RocketWerkz.Brutal.Interop.NativeBuild

The source generator packages are bundled with RocketWerkz.Brutal.Ast and Ahwoo.BRUTAL.Interop respectively and do not need to be installed separately.

Usage

Each module ships with a guided walkthrough next to its source — start at src/Brutal.Ast/README.md for the core IR, or jump straight to src/Brutal.Interop/README.md for the runtime handle pattern. The code samples on those pages are compiled and asserted at build time via RocketWerkz.Brutal.DocTest, so they stay in sync with the API.

samples/Brutal.Ast.Samples contains runnable end-to-end samples that demonstrate the full interop generation workflow:

• AutoInterop — The core workflow: parses a C++ API, generates a C extern wrapper, a C# PInvoke layer, and a user-facing C# wrapper in one pass.
• Comprehensive — Extends AutoInterop with custom AST manipulation and additional hand-written C# files, showing how auto-generated code can be augmented.
• FullGeneration — Demonstrates standalone code generation without a native compilation step.
• DocComments — Shows how C# doc comments can be authored using the DocComment tree
• CMakeParser — Investigates cmake parsing with the intention of informing how code should be parsed for generation

AutoInterop, Comprehensive, FullGeneration, and CMakeParser compile native libraries at runtime and require CMake and a platform C++ toolchain to be available on PATH (MSVC on Windows, GCC on Linux, Xcode Command Line Tools on macOS). DocComments has no native compilation step. libclang itself is bundled with RocketWerkz.Brutal.Ast.CppAst and does not need to be installed separately.

Please refer to the BRUTAL Documentation for more detailed usage instructions and examples.

For Developers

Prerequisites

• .NET SDK (version 10.0 or later)

Compilation and Testing

To build the solution locally, run the following command in the repository root:

dotnet build

To run the tests, run the following command in the repository root:

dotnet test

Contributing

If you find a bug or have a feature request, please open an issue on GitHub. If you'd like to contribute code, feel free to fork the repository and submit a pull request.