repository·main·Indexed 22 days ago
https://github.com/dotnet/clangsharpC# bindings for Clang that enable the development of C/C++ tooling within the .NET ecosystem. It provides three levels of abstraction: a raw unsafe API, a type-safe abstraction, and a C++ type hierarchy abstraction. The project includes the ClangSharpPInvokeGenerator .NET tool for auto-generating P/Invoke bindings from C header files, as well as helper packages like libclang and libClangSharp.
ClangSharp consists of several packages depending on your requirements:
clangsharp: The core C# bindings for Clang.ClangSharpPInvokeGenerator: A .NET tool used to auto-generate bindings by parsing Clang C header files.libclang: A convenience meta-package providing the native libClang library for several platforms.libClangSharp: A helper meta-package that exposes many Clang APIs missing from the standard libClang library.ClangSharp provides C# bindings for Clang C headers, allowing you to build tooling around C/C++ code. It offers three levels of abstraction:
CXIndex and CXTranslationUnit) to improve type safety.The C# API is designed to be nearly identical to the Clang C APIs, with minor syntax adjustments (e.g., clang_getDiagnosticSpelling in C becomes clang.getDiagnosticSpelling in C#).
Beyond generating bindings, ClangSharp can be used directly as a library to parse C/C++ code and inspect the resulting Abstract Syntax Tree (AST).
Note: This is an advanced use case. The Clang APIs are the source of truth, so familiarity with Clang is required. For details on how Clang C functions and the C++ AST map to ClangSharp.Interop and ClangSharp surfaces, including IDisposable lifetime management and package references, refer to the Using ClangSharp as a library documentation.
ClangSharp objects that own native resources implement IDisposable. You must wrap them in using blocks to ensure resources are released, equivalent to calling clang_dispose* in C.
Key types to manage:
CXIndex: Created via CXIndex.Create(); must be disposed.TranslationUnit: Obtained via TranslationUnit.GetOrCreate(...); disposing it releases the underlying CXTranslationUnit.Warning: Using a cursor or type after its owning TranslationUnit has been disposed results in undefined behavior.
Many name-matching options (like --with-* or --without-*) support glob patterns:
*: Matches any run of characters, including qualification separators.?: Matches a single character.Catch-all and Overrides:
* as a bare value to apply a rule to everything. For valued options, use the syntax *=value (e.g., --with-access-specifier *=Internal).--with-<name> option has a paired --without-<name> option to opt a specific declaration back out of a catch-all rule.-i (include) and -e (exclude) together to opt everything in and then exclude specific items piecemeal. Both accept globs.The ClangSharp.Interop layer maps libClang C functions to C# as follows:
clang_ are exposed as static methods on the clang class, with the clang_ prefix dropped and the first character preserved (e.g., clang_getCursorType(CXCursor C) becomes clang.getCursorType(cursor)).CX* types for more natural syntax (e.g., cursor.Type instead of clang.getCursorType(cursor)).CX* handle types (like CXIndex, CXTranslationUnit, CXCursor) retain their original names.When the binding requires C# code that cannot be represented by structured XML (such as initializer expressions, generated helper bodies, or complex logic), the generator emits the raw C# text inside a <code> element. This is commonly seen inside <value> elements for enums/constants or <body elements for functions.
<value>
<code>1_024.0</code>
</value>The high-level ClangSharp layer mirrors the Clang C++ class hierarchy:
Cursor is the base type. Decl, Stmt, Expr, and Type (along with subclasses like FunctionDecl, CallExpr, and ReturnStmt) derive from it.TranslationUnit via the TranslationUnitDecl property.new to create these types; instead, use TranslationUnit.GetOrCreate(...), which returns the same managed object for a given underlying handle. This makes reference equality meaningful.Most name-matching options (like --with-access-specifier or --with-callconv) accept glob patterns:
*: Matches any run of characters, including :: or . separators.?: Matches a single character.Rules for matching:
Common Patterns:
*=value to apply a rule to everything (e.g., --with-callconv *=Winapi).PFN* to match all callback types.--with-<name> option has a paired --without-<name> option to exclude specific declarations from a catch-all rule.# Example: Make all 'Flags' types internal and all 'PFN' callbacks Winapi
--with-access-specifier
*Flags=Internal
--with-callconv
PFN*=Winapi# Example: Make every type whose name ends in "Flags" internal, and give every "PFN" callback the Winapi convention
--with-access-specifier
*Flags=Internal
--with-callconv
PFN*=Winapi
# Example: Apply a rule to everything
--with-callconv
*=Winapi
# Example: Opt-out of a catch-all
--with-access-specifier
*=Internal
--without-access-specifier
Foo
--without-access-specifier
Bar*ClangSharp provides two distinct surfaces for interacting with Clang:
ClangSharp.Interop: A low-level layer providing 1:1 bindings to the libClang stable C API. It uses clang_* prefixed static methods on a clang class and CX* handle types (e.g., CXCursor, CXType).ClangSharp: A high-level layer that mirrors the Clang C++ AST. It provides managed objects like Cursor, Decl, Stmt, Expr, and Type (and their subclasses like FunctionDecl or CallExpr) which are easier to work with in .NET.Because these layers mirror upstream Clang, you should refer to the official Clang documentation for understanding the semantics of the APIs.
To manage large binding projects, categorize your ClangSharpPInvokeGenerator options into shared and per-target settings to avoid duplication and ensure consistency.
settings.rsp)Use these for properties that should be identical across the entire project:
-m64) and warning suppressions (e.g., -Wno-comment, -Wno-deprecated-declarations).--config mode families, --generate, and --log switches.--define-macro values that shape header exposure (e.g., UNICODE, INITGUID).--include-directory paths for local headers and SDKs.--header-file and project-wide call convention rules like --with-callconv *=Winapi.remap-handles.rsp) to ensure types like HANDLE are mapped consistently everywhere.generate.rsp)Use these for properties unique to a specific header:
--file (the umbrella header), --traverse, --namespace, --method-class-name, --output, and --test-output.--exclude, --with-attribute, and --with-library-path.A generated XML file is a single <bindings> document. The hierarchy typically follows this pattern:
<bindings>: The root element.<comment>: Contains the verbatim header text if --header-file was configured.<namespace name="...">: Represents the declared namespace (from -n).<class name="..." ...>: A static holder for free functions (from -m or --method-class-name). Types like structs and enums are placed directly under the <namespace>, not inside this class.In --multi-file mode, each generated file is its own complete <bindings> document.
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<bindings>
<namespace name="ClangSharp.Test">
<class name="Methods" access="public" static="true">
<function name="MyFunction" access="public" lib="ClangSharpPInvokeGenerator" convention="Cdecl" static="true" unsafe="true">
<type>void</type>
<param name="color">
<type>float*</type>
</param>
</function>
</class>
</namespace>
</bindings>