ClangSharp: C# bindings for libClang, generated by libClang

A binding layer that regenerates itself from the headers

ClangSharp provides Clang bindings written in C#, and the interesting property is stated in the first line of the description: it is self-hosted and auto-generates itself by parsing the Clang C header files using ClangSharpPInvokeGenerator. That closes a loop that is normally awkward. The bindings are produced by the Clang library itself, through a generator that is also part of this project, so the C# surface tracks the actual Clang headers rather than a hand-maintained description of them. The consequence for the user is that the API is wide rather than curated. The feature list says the bindings are auto-generated using the Clang C header files and support all functionality exposed by them, which means you can build tooling around C and C++ from C#, but it also means you are working with a generated surface of the size of Clang itself rather than a small friendly wrapper. The generator ships separately as a .NET tool, ClangSharpPInvokeGenerator, and the documentation in docs/ covers the best practices for generating bindings and the XML binding format.

Four layers, and you pick which one you stand on

The feature list describes an API that is deliberately graduated. The lowest layer exposes the raw unsafe API for performance, which is the direct P/Invoke surface with pointer types. Above that is a slightly higher abstraction that is type safe, where CXIndex and CXTranslationUnit are different types even though they are pointers internally, which removes a class of mistake at the cost of some indirection. Above that sits an abstraction that tries to mirror the Clang C++ type hierarchy where possible. Across the layers the naming stays nearly identical to the Clang C API: clang_getDiagnosticSpelling in C becomes clang.getDiagnosticSpelling in C#, with the dot instead of the underscore. That naming discipline is not cosmetic. It means an example from Clang documentation, or a code snippet from a search engine, translates to C# by changing the call style rather than requiring you to look up a different name, and it means the type hierarchy you already know applies to the managed version.

Four packages, and the native ones are meta-packages

Distribution is through NuGet, and the package layout is where the practical friction lives. The main package is clangsharp. The generator is ClangSharpPInvokeGenerator, published as a .NET tool, with a note that running it as a dotnet tool may require manually copying the appropriate DLLs from NuGet because of limitations in dotnet tool support. A convenience package called libclang provides the native libClang library for several platforms. And libClangSharp is a helper package exposing many Clang APIs that are missing from libClang. The last two are meta-packages that point to platform-specific runtime packages, and the README is explicit that several manual steps may be required to use them, pointing at issue 46 and issue 118 for the discussion. That is the sharpest edge in the whole project: the managed side installs like an ordinary package, and the native side is a set of per-platform runtime packages with a hand-configuration step, so the first hour of using ClangSharp is often spent working out which native package your target framework and runtime identifier actually need.

Building the managed side: .NET 10 and a script with a dependency chain

ClangSharp requires the .NET 10 SDK and can be built with a single command:

dotnet build -c Release

To reproduce what CI does, the README points at ./scripts/cibuild.cmd on Windows or ./scripts.cibuild.sh on Unix, which download the required .NET SDK locally, build the repository with it and run through the available actions in order. Beyond that there are several build scripts in the repository root, and their argument convention is spelled out because it is easy to get wrong. On Windows the scripts end in .cmd and take arguments with a dash prefix, on Unix they end in .sh and take a double dash prefix. By default each script performs only the action named in the script, so restore only restores, build only builds, test only tests and pack only packs, and you compose them by naming the extra actions, for example build.cmd -restore to restore and build. The dependency chain matters: build depends on restore, test depends on build, and pack depends on build, so the recommended first run is build -restore. The tree also carries the usual .NET build plumbing, with Directory.Build.props, Directory.Build.targets, Directory.Packages.props, global.json, NuGet.config, Open.snk for signing and a set of build, restore, test and pack scripts.

Building the native helper means building Clang first

ClangSharp also ships a helper library, libClangSharp, that exposes additional functionality not available in libClang, and building it is a separate and much longer task. It requires CMake 3.13 or later and a version of MSVC or Clang that supports C++ 17, and to build it you must first build Clang. The documented Linux sequence clones the LLVM project at the branch llvmorg-22.1.8, creates an artifacts/bin directory and configures it with the clang project enabled:

git clone --single-branch --branch llvmorg-22.1.8 https://github.com/llvm/llvm-project
cd llvm-project
mkdir -p artifacts/bin
cd artifacts/bin
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../install -DLLVM_ENABLE_PROJECTS=clang ../../llvm
make install

For a portable Linux build the documentation suggests turning off terminfo, zlib and zstd and statically linking the C++ standard library, through the LLVM_ENABLE_TERMINFO, LLVM_ENABLE_ZLIB, LLVM_ENABLE_ZSTD and LLVM_STATIC_LINK_CXX_STDLIB options, and it notes that if you prefer Ninja you should pass -G Ninja and invoke ninja rather than make install. The Windows path uses the Visual Studio 17 2022 generator with the x64 platform and host, opens LLVM.slnx, builds the ALL_BUILD project if needed and then the INSTALL project. The second stage configures libClangSharp with a PATH_TO_LLVM pointing at the install prefix produced by the first. This is a heavy build, which is why the convenience native packages exist.

Where ClangSharp is the wrong tool

The limits follow from what the project is. First, the bindings are specific to Clang. ClangSharp is a way to call libClang from C#, not a general C# wrapper generator, and the P/Invoke generator is aimed at the Clang surface. If your goal is to call some other native library from .NET, this is the wrong package. Second, the native side is a real dependency chain: a per-platform runtime package, a meta-package, and in the case of libClangSharp a native build you may have to produce yourself against a matching LLVM. The mismatch between the ClangSharp package version and the LLVM version that the native package wraps is another source of friction, and the fact that the native packages are meta-packages with manual steps means a first-time setup is not a single install. Third, the API is generated, so it inherits Clang's own shape, including its C heritage. CXString and CXSourceLocation are the kind of types that need careful handling in managed code, and the raw unsafe layer is exposed precisely because the higher layers cost something. If your .NET code is going to be a long-lived library, you are signing up to maintain a dependency on a moving LLVM release train.

How this compares with writing P/Invoke by hand

The alternative is what most teams do first: write the P/Invoke declarations yourself, one DllImport per function, with the calling convention, the marshalling and the struct layouts worked out from the Clang headers by hand. The difference in approach is that ClangSharp automates the part that is tedious and error-prone, and adds structure to the part that is not. Hand-written declarations are usually a flat list of functions with primitive and pointer parameters, and the marshalling rules are whatever you decided. The generated version keeps three levels available, so a performance-critical path can drop to the raw unsafe layer while the rest of the code uses the type-safe abstraction where CXIndex and CXTranslationUnit are distinct types, and the naming stays close to the C API so documentation transfers. The cost is that the generated surface is large and the library itself becomes something you depend on rather than something you wrote, and you inherit the setup complexity of the native packages. For a handful of libClang calls, hand-written declarations are less work. For a tool that parses a large codebase with Clang, the generated bindings and the maintained type hierarchy save considerably more than they cost.

Editorial conclusion

Adopt ClangSharp if you are building .NET tooling that has to parse or analyse C and C++ and want typed access to libClang without hand-writing P/Invoke signatures. Do not adopt it as a general C# wrapper generator, because the bindings are specific to Clang's own API and the generator is aimed at that surface. Before you start, note that the package version and the LLVM version move separately, that the native libclang and libClangSharp packages are meta-packages that need extra manual steps as described in the linked issues, and that building the native helper requires you to build Clang yourself with CMake 3.13 or later and a C++ 17 compiler.

Frequently asked questions

Official sources

1. dotnet/ClangSharp on GitHub
2. Issues
3. License: MIT
4. README
5. Releases