DOCSEARCHbyAlgolia
Submit Docs

LLVMSharp Documentation

repository·main·Indexed 21 days ago

https://github.com/dotnet/llvmsharp

Multi-platform .NET Standard bindings for the LLVM infrastructure, enabling .NET developers to build compilers and tools. The API is auto-generated from LLVM C headers via ClangSharp, providing type safety and functionality parity with the LLVM C APIs. Includes the Kaleidoscope tutorial, a C# port of the LLVM tutorial demonstrating language construction, JIT, optimization, and DWARF debug information.

Tokens
1.3K
Snippets
6
Records
8
Agent score
26%

What's inside LLVMSharp

  1. Understand the LLVMSharp API design

    main

    The LLVMSharp API is auto-generated from LLVM C headers using ClangSharp. It follows these design principles:

    • Functionality Parity: It supports all functionality exposed by the LLVM C APIs.
    • Type Safety: While many LLVM types are pointers internally, LLVMSharp provides distinct types for them (e.g., LLVMValueRef and LLVMTypeRef are different types in C#) to ensure type safety.
    • API Mapping: The C# API is nearly identical to the LLVM C API, but uses dot notation for method calls. For example, the C function LLVMModuleCreateWithName becomes LLVM.ModuleCreateWithName in C#.

  2. Build LLVMSharp from source

    main

    You can build LLVMSharp using the .NET CLI.

    On Linux

    $ git clone http://github.com/dotnet/llvmsharp
$ cd LLVMSharp
$ dotnet build

    On Windows

    Note: You must run these commands from the Visual Studio Developer Command Prompt.

    $ git clone http://github.com/dotnet/LLVMSharp
$ cd LLVMSharp
$ dotnet build
    # Linux example
$ git clone http://github.com/dotnet/llvmsharp
$ cd LLVMSharp
$ dotnet build

  3. Compile Kaleidoscope with DWARF debug information (Chapter 9)

    main

    Chapter 9 is a version of the Chapter 8 batch compiler that includes DWARF debug information. It generates DICompileUnit, DISubprogram, DILocalVariable, and !dbg source locations for every instruction, enabling step-through debugging in standard debuggers.

    To compile a program with debug info:

    echo "def fib(n) if n < 3 then 1 else fib(n - 1) + fib(n - 2);" | dotnet run --project Chapter9 -c Release

  4. Run Kaleidoscope tutorial tests

    main

    The tutorial samples are validated by the LLVMSharp.KaleidoscopeTests project. These tests launch each chapter as a subprocess, feed it a script, and assert the correctness of the emitted IR, evaluated results, or generated object files.

    To run the tests:

    dotnet build -c Release
dotnet test -c Release --no-build --filter "FullyQualifiedName~KaleidoscopeTests"

  5. Run the Kaleidoscope Tutorial samples

    main

    The Kaleidoscope tutorial is a C# port of the LLVM tutorial, demonstrating how to use LLVMSharp to build a functional language. The project is structured so that each chapter contains only the delta (new features) over the previous one, with shared logic residing in Kaleidoscope.Common.

    Prerequisites

    • .NET 10 preview SDK (as specified by the repository's global.json).

    Build and Run

    To build the entire tutorial solution:

    dotnet build KaleidoscopeTutorial.slnx -c Release

    To run a specific chapter (e.g., Chapter 4, which adds JIT and optimization):

    dotnet run --project Chapter4 -c Release
    dotnet build KaleidoscopeTutorial.slnx -c Release
dotnet run --project Chapter4 -c Release

  6. Install LLVMSharp via NuGet

    main

    LLVMSharp is a multi-platform .NET Standard library for accessing LLVM infrastructure. To use it in your project, install the following NuGet packages:

    • llvmsharp: The main managed bindings.
    • libLLVM: A convenience meta-package that provides the necessary native libLLVM library for several platforms.

    You can find these packages on NuGet.org.

  7. Compile Kaleidoscope to a native object file (Chapter 8)

    main

    Chapter 8 acts as a batch compiler. It reads a complete Kaleidoscope program and emits a native object file (defaulting to output.o). The resulting object exports functions using the C ABI (e.g., double func(double, double)), allowing them to be linked into C or C++ programs.

    To compile a program from stdin to an object file:

    echo "def average(x y) (x + y) * 0.5;" | dotnet run --project Chapter8 -c Release

  8. Use Kaleidoscope REPL (Chapters 3–7)

    main

    Chapters 3 through 7 operate as a REPL (Read-Eval-Print Loop). They read Kaleidoscope code from stdin or from a file passed as the first argument.

    Example inputs for different language features:

    Basic functions and externs:

    def fib(x) if x < 3 then 1 else fib(x - 1) + fib(x - 2);
fib(10);

extern sin(x);
sin(1.0);

    User-defined operators (Chapter 6+):

    def unary!(v) if v then 0 else 1;
!0;

    Mutable variables (Chapter 7+):

    def binary : 1 (x y) y;
def fibi(x) var a = 1, b = 1, c in (for i = 3, i < x in c = a + b : a = b : b = c) : b;
fibi(10);
    def fib(x) if x < 3 then 1 else fib(x - 1) + fib(x - 2);
fib(10);

extern sin(x);
sin(1.0);

# user-defined operators (chapter 6+)
def unary!(v) if v then 0 else 1;
!0;

# mutable variables (chapter 7+)
def binary : 1 (x y) y;
def fibi(x) var a = 1, b = 1, c in (for i = 3, i < x in c = a + b : a = b : b = c) : b;
fibi(10);