Clang bindings for .NET written in C#.zip

# 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. [](https://github.com/dotnet/ClangSharp/actions/workflows/ci.yml) 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.](https://www.nuget.org/packages/libClangSharp.runtime.win-x64/17.0.4); see others owned by [tannergooding](https://www.nuget.org/profiles/tannergooding)). Several manual steps may be required to use them, see discussion in [#46](https://github.com/dotnet/ClangSharp/issues/46) and [#118](https://github.com/dotnet/ClangSharp/issues/118). Nightly packages are available via the NuGet Feed URL: https://pkgs.clangsharp.dev/index.json Source browsing is available via: https://source.clangsharp.dev/ ## Table of Contents * [Code of Conduct](#code-of-conduct) * [License](#license) * [Features](#features) * [Building Managed](#building-managed) * [Building Native](#building-native) * [Generating Bindings](#generating-bindings) * [Using locally built versions](#using-locally-built-versions) * [Spotlight](#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](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 8 SDK](https://dotnet.microsoft.com/download/dotnet/8.0) 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](https://cmake.org/download/) 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: ```cmd git clone --single-branch --branch llvmorg-17.0.4 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.sln` in Visual Studio, change the configuration to `Release` and build the `install` project. Afterwards, you can then build `libClangSharp` where the process followed is roughly: ```cmd 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=../../../../llvm-project/artifacts/install -G "Visual Studio 17 2022" -A x64 -Thost=x64 ../../.. ``` You can then open `libClangSharp.sln` in Visual Studio, change the configuration to `Release` and build the `install` project. #### Linux The process done on Linux is roughly: ```bash git clone --single-branch --branch llvmorg-17.0.4 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: ```cmd 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 ``` ### 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 --version 17.0.0 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. The full set of available switches: ``` ClangSharpPInvokeGenerator ClangSharp P/Invoke Binding Generator Usage: Clan