ClangSharp

ClangSharp

ClangSharp provides Clang bindings written in C#. It is self-hosted and auto-generates itself by parsing the Clang C header files using ClangSharpPInvokeGenerator. A nuget package for the project is provided here: https://www.nuget.org/packages/clangsharp. A .NET tool for the P/Invoke generator project is provided here: https://www.nuget.org/packages/ClangSharpPInvokeGenerator

NOTE: If you are running as a dotnet tool, you may need to manually copy the appropriate DLLs from NuGet due to limitations in the dotnet tool support.

A convenience package which provides the native libClang library for several platforms is provided here: https://www.nuget.org/packages/libclang

A helper package which exposes many Clang APIs missing from libClang is provided here: https://www.nuget.org/packages/libClangSharp

NOTE: libclang and libClangSharp are meta-packages which point to the platform-specific runtime packages (e.g.; see others owned by tannergooding). Several manual steps may be required to use them, see discussion in #46 and #118.

Source browsing is available via: https://source.clangsharp.dev/

Table of Contents

• Code of Conduct
• License
• Features
• Building Managed
• Building Native
• Regenerating native binaries
• Generating Bindings
  • Best practices
  • XML binding format
• Using as a Library
• Using locally built versions
• Spotlight

Code of Conduct

ClangSharp and everyone contributing (this includes issues, pull requests, the wiki, etc) must abide by the .NET Foundation Code of Conduct: https://dotnetfoundation.org/about/code-of-conduct.

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at [email protected].

License

Copyright (c) .NET Foundation and Contributors. All Rights Reserved. Licensed under the MIT License (MIT). See LICENSE.md in the repository root for more information.

Features

• Auto-generated using Clang C headers files, and supports all functionality exposed by them ~ which means you can build tooling around C/C++
• Exposes the raw unsafe API for performance
• Exposes a slightly higher abstraction that is type safe (CXIndex and CXTranslationUnit are different types, despite being pointers internally)
• Exposes an again slightly higher abstraction that tries to mirror the Clang C++ Type Hierarchy where possible
• Nearly identical to the Clang C APIs, e.g. clang_getDiagnosticSpelling in C, vs. clang.getDiagnosticSpelling (notice the . in the C# API)

Building Managed

ClangSharp requires the .NET 10 SDK and can be built simply with dotnet build -c Release.

You can reproduce what the CI environment does by running ./scripts/cibuild.cmd on Windows or ./scripts.cibuild.sh on Unix. This will download the required .NET SDK locally and use that to build the repo; it will also run through all available actions in the appropriate order.

There are also several build scripts in the repository root. On Windows these scripts end with .cmd and expect arguments with a - prefix. On Unix these scripts end with .sh and expect arguments with a -- prefix. By default, each script performs only the action specified in its name (i.e. restore only restores, build only builds, test only tests, and pack only packs). You can specify additional actions to be run by passing that name as an argument to the script (e.g. build.cmd -restore will perform a package restore and build; test.cmd -pack will run tests and package artifacts). Certain actions are dependent on a previous action having been run at least once. build depends on restore, test depends on build, and pack depends on build. This means the recommended first time action is build -restore.

You can see any additional options that are available by passing -help on Windows or --help on Unix to the available build scripts.

Building Native

ClangSharp provides a helper library, libClangSharp, that exposes additional functionality that is not available in libClang. Building this requires CMake 3.13 or later as well as a version of MSVC or Clang that supports C++ 17.

To successfully build libClangSharp you must first build Clang (https://clang.llvm.org/get_started.html).

Windows

The process done on Windows is roughly:

git clone --single-branch --branch llvmorg-22.1.8 https://github.com/llvm/llvm-project
cd llvm-project
mkdir artifacts/bin
cd artifacts/bin
cmake -DCMAKE_INSTALL_PREFIX=../install -DLLVM_ENABLE_PROJECTS=clang -G "Visual Studio 17 2022" -A x64 -Thost=x64 ../../llvm

You can then open LLVM.slnx in Visual Studio, change the configuration to Release and build the INSTALL project. You may need to build the ALL_BUILD first.

Afterwards, you can then build libClangSharp where the process followed is roughly:

git clone https://github.com/dotnet/clangsharp
cd clangsharp
mkdir artifacts/bin/native
cd artifacts/bin/native
cmake -DCMAKE_INSTALL_PREFIX=../install -DPATH_TO_LLVM=absolute/path/to/repos/llvm-project/artifacts/install -G "Visual Studio 17 2022" -A x64 -Thost=x64 ../../..

You can then open libClangSharp.slnx in Visual Studio, change the configuration to Release and build the INSTALL project.

Linux

The process done on Linux is roughly:

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

If you want your Linux build to be portable, you may also consider specifying the following options:

• -DLLVM_ENABLE_TERMINFO=OFF
• -DLLVM_ENABLE_ZLIB=OFF
• -DLLVM_ENABLE_ZSTD=OFF
• -DLLVM_STATIC_LINK_CXX_STDLIB=ON

If you would prefer to use Ninja, then make sure to pass in -G Ninja and then invoke ninja rather than make install.

Afterwards, you can then build libClangSharp where the process followed is roughly:

git clone https://github.com/dotnet/clangsharp
cd clangsharp
mkdir -p artifacts/bin/native
cd artifacts/bin/native
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../install -DPATH_TO_LLVM=../../../../llvm-project/artifacts/install ../../../
make install

Regenerating native binaries

The native runtime packages are produced by CI (.github/workflows/regenerate-native.yml) rather than by hand:

• libclang.runtime.* (and the libclang meta-package) — the prebuilt libclang shared library, lifted directly from the matching official LLVM release.
• libClangSharp.runtime.* (and the libClangSharp meta-package) — the libClangSharp helper, compiled from sources/libClangSharp against that same LLVM release.

The tracked LLVM version is the project(ClangSharp VERSION X.Y.Z) value in the top-level CMakeLists.txt, which maps to the llvmorg-X.Y.Z release tag. For each runtime (win-x64, win-arm64, linux-x64, linux-arm64, osx-arm64) the download-and-stage step is handled by scripts/build.ps1/scripts/build.sh:

# lift the prebuilt libclang out of the matching LLVM release
./scripts/build.sh --regeneratenative --target libclang --rid linux-x64

# compile libClangSharp against that same LLVM release
./scripts/build.sh --regeneratenative --target libClangSharp --rid linux-x64

The change-detection and version-verification the workflow gates on live in the same scripts, so they can be reproduced locally: ./scripts/build.sh --detectchanges --base prints which families a range of commits regenerates, and ./scripts/build.sh --verifypackages checks the nuspec/runtime.json versions match the tracked LLVM version.

The staged binary is written to artifacts/native//. The LLVM release distribution bundles both the prebuilt libclang and the lib/cmake/{llvm,clang} config, headers, and import libraries used as PATH_TO_LLVM when building libClangSharp, so no from-source LLVM build is required (the manual Building Native steps remain the way to reproduce a build locally). Because lifting libclang is just unpacking prebuilt binaries, the workflow does all five runtimes on a single Windows runner (its bundled bsdtar handles .tar.xz); libClangSharp is compiled per-runtime on native runners.

The win-arm64 runtime is compiled with the LLVM release's own clang-cl (via -G Ninja) rather than MSVC. The official LLVM binaries are clang-built, and on Arm64 clang and MSVC disagree on the record layout of over-aligned non-POD base classes (e.g. clang::TemplateSpecializationType), so an MSVC-built shim reads members of clang-built types at the wrong offset. The other runtimes are unaffected (win-x64 layouts agree between the two, and the Unix runtimes already use clang).

The jobs run when:

• libclang — the tracked LLVM major/minor version changes, or the workflow is dispatched manually with the libclang input set.
• libClangSharp — the same LLVM version change, or anything under sources/libClangSharp/ changes, or the workflow is dispatched manually with the libclangsharp input set.

Before anything is downloaded, the workflow verifies the packages/**/*.nuspec and packages/**/runtime.json versions match the tracked LLVM version (libclang exactly; libClangSharp as .), so a version bump that forgot to update a package fails fast. Each job uploads the resulting .nupkg files as build artifacts and signs them; publishing them to NuGet.org is a manual step. To move to a new LLVM release, bump the version in CMakeLists.txt alongside the `` in the affected packages/**/*.nuspec files (and the versions in packages/**/runtime.json and this README); pushing that change regenerates the packages.

Generating Bindings

This program will take a given set of C or C++ header files and generate C# bindings from them. It is still a work-in-progress and not every declaration can have bindings generated today (contributions are welcome).

The simplest and recommended setup is to install the generator as a .NET tool and then use response files:

dotnet tool install --global ClangSharpPInvokeGenerator
ClangSharpPInvokeGenerator @generate.rsp

A response file allows you to specify and checkin the command line arguments in a text file, with one argument per line. For example: https://github.com/dotnet/ClangSharp/blob/main/sources/ClangSharpPInvokeGenerator/Properties/GenerateClang.rsp At a minimum, the command line expects one or more input files (-f), an output namespace (-n), and an output location (-o). A typical response file may also specify explicit files to traverse, configuration options, name remappings, and other fixups.

For an opinionated walkthrough of how to structure a real generation project — response-file composition, the key options and when to use them, incremental regeneration, and common pitfalls — see Generating bindings: best practices.

The generator can also emit its bindings as XML rather than C# via --output-mode Xml; the shape of that output is described in The XML binding format.

The full set of available switches:

…

The available configuration options (visible with -c help) are:

…

Using as a Library

In addition to generat