netmf / llvm.net

LLVM Bindings for .NET

Active Development of Llvm.NET has moved

Active development of Llvm.NET has moved to Ubiquity.NET This is to better support future projects leveraging LLVM.NET under a single GitHub organization isolated from the legacy .NET Micro Framework interpreter engine contained in the NETMF organization to help prevent confusion between the projects.

Llvm.NET

Welcome to Llvm.NET!

Llvm.NET provides LLVM language and runtime bindings for .NET based applications. Llvm.NET's goal is to provide as robust Class library that accurately reflects the underlying LLVM C++ model. This is done through an extend LLVM-C API bundled as a native windows DLL (LibLLVM.DLL). Llvm.NET uses the support of LibLLVM to gain access to the LLVM class library and project it into a .NET managed library that reflects the original class library design.
The goal is to match the original class model as closely as possible, while providing an object model to .NET applications that feels familiar and consistent with common styles and patterns in .NET Framework applications. Thus, while class, method and enumeration names are similar to their counterparts in LLVM, they are not always identical.

Documentation

Documentation for using the Llvm.NET class library is located at http://netmf.github.io/Llvm.NET

Why Llvm.NET?

Llvm.NET was initially developed as a means to leverage LLVM as the back-end for an Ahead-Of-Time (AOT) compilation tool for .NET applications targeting micro controllers (e.g. An AOT compiler for the .NET Micro Framework ). The initial proof of concept built on Llvm.NET was successful in delivering on a basic application that could implement the micro controller equivalent of the classic "Hello World!" application (e.g. Blinky - an app that blinks an LED) using LLVM as the back-end code generator. This led to the revival of a former project doing AOT with its own code generator that was tied to the ARMv4 Instruction set. (Llilum). Llvm.NET has continued to evolve and improve and remains a distinct project as it has no dependencies on Llilum or any of its components. Llvm.NET is viable for any .NET applications wishing to leverage the functionality of the LLVM libraries from .NET applications.

Brief History

Llvm.NET began with LLVM 3.4 as a C++/CLI wrapper which enabled a closer binding to the original C++ object model then the official LLVM-C API supported. As Llvm.NET progressed so to did LLVM. Eventually the LLVM code base migrated to requiring C++11 support in the language to build. This became an issue for the C++/CLI wrapper as the Microsoft C++/CLI compiler didn't support the C++11 syntax. Thus a change was made to Llvm.NET to move to an extended C API with a C# adapter layer to provide the full experience .NET developers expect. While the transition was a tedious one very little application code required changes.

Platform Support

Currently LLVM.NET supports Win32 and x64 buids targeting the full desktop framework v4.7, though it is intended to support .NET Standard 2.0 so that more platforms are possible in the future. To keep life simpler the Llvm.NET nuget package is built for the "AnyCPU" platform and references the LibLLVM.NET package to bring in the native binary support. Llvm.NET contains code to dynamically detect the platform it is running on and load the appropriate DLL. This allows applications to build for AnyCPU without creating multiple build configurations and release vehicles for applications.

Building Llvm.NET

Pre-requsites

• Download LLVM 4.0.1
  • You will need a tool to extract files from that archive format. On Windows the recommended tool is 7zip
• Build of LLVM libraries
  To Build the LLVM libraries you can use the Build-LlvmWithVS PowerShell script provided. For more information on using the script open a PowerShell command prompt in the Llvm.NET source directory and run PS> Get-Help .\Build-LlvmWithVs.ps1.

NOTE: On a typical developer machines the LLVM library build takes approximately 1.5 hours so letting it run overnight or when you are otherwise away from your computer is usually a good idea. Fortunately this only needs to be done once for a given release of LLVM.

If you have Visual Studio 2017 RC (or RTM when available) with the Visual C++ Tools for CMake, you can build the LLVM libs in VS. However, the default behavior is to build everything, which can take upwards of 6 hours on most typical machines. Instead of doing a full build you can use the Build-LlvmWithVS PowerShell script with the -CreateSettingsJson to create the CMakeSettings.json file that VS will use to configure VS to reduce what is built to just the libraries needed for Llvm.NET.

Using Visual Studio

The repository contains a Visual Studio solution files that allow building the components individually for modifying Llvm.NET and LibLLVM, as well as running the available unit tests. This is the primary mode of working with the Llvm.NET source code duing development.

Replicating the automated build

The Automated build support for Llvm.NET uses BuildAll.ps1 powershell script to build all the binaries, sign them [SHA256 hash only at present], and generate a nuget package. To build the full package simply run BuildAll.ps1 from a powershell command prompt with msbuild tools on the system search path.

Sample Application

The CodeGenWithDebugInfo sample application provides an example of using Llvm.NET to generate LLVM Bit code equivalent to what the Clang compiler generates for a simple C language file. TestDebugInfo doesn't actually parse the source, instead it is a manually constructed and documented example of how to use Llvm.NET to accomplish the bit-code generation.

Code of Conduct

This project has adopted the code of conduct defined by the Contributor Covenant to clarify expected behavior in our community. For more information, see the .NET Foundation Code of Conduct.

llvm.net's Issues

Function attribute checks don't validate power of 2 for alignment

The function attributes support in Function.cs don't verify that the stack alignment values must be powers of 2 (It only verifies bit width)

Re-work Static State to allow moving the native method static constructor

The current mechanism for loading the LibLLVM.dll is a static constructor. While this has the advantage of being transparent it can cause TypeLoad exceptions if the library can't be loaded. Moving that to an application called initialize function eliminates the exception and also allows for properly handling llvmshutdown() calls (via a returned IDisposable)

Is this project continuted?

Last updated four days ago.
This project has not been updated for a long time
In this case, it seems possible to use the C # programming language to develop the MCU
@smaillet

NativeModule is not unregistered from the ModuleCache

If a NativeModule is disposed, the ModuleCache in the Context class will not be updated with this information. Thus, the (already diposed) NativeModule resides in the ModuleCache.

Why two bindings?

What is advantage of this binding over https://github.com/Microsoft/LLVMSharp?

The reason prefer llvm 4.01 rather than 5.0.

Sure we know llvm 5.0 is in rc+ status, but not so far for a final release.
Will llvm.net branch 4.01 be easily transfered to adapt llvm 5.0, or else if there is huge obstacle to resolve so make branch 4.01 more important?

re-enable CA1062 and fix all parameter check errors

i have some questions ......

Hello! I come from Shenzhen, China. Glad to see this project. I have some questions to ask.
1.Intermediate, Signed, Unsigned. I see there are LibLLVM.DLL, Llvm.NET.DLL. What is the difference between these folders?
2 I am an embedded Engineer (ARM Cortex-M0+/M3/M4 Engineer). I want a LLVM based C# compiler. You can generate the HEX/ELF file by entering the source code files and the link script file. This function can be achieved? Because I don't understand LLVM, I need a EXE program. Achieve "CS files ------->elf file" function. Please help me. Thank you.
3 to provide the necessary libraries, such as" System.Convert class, string class, List<> class " etc..
4 if the microcontroller project without RTOS, then how to deal with GC? Because the microcontroller project with RTOS words, you can put GC into the IDLE thread.
Finally, I hope you come to China to play. ( ^_^ )

Update to 3.80 RTM

Currently only tested and supported on RC1 (Don't expect any issues but need to rebuild the libs and test)

Split Llvm.NET BuildTasks DLL and Nuget to isolate functionality and version ALL builds.

The current buildtasks actually cover 3 distinct scenarios:

1. Native C++ multi targeted builds
2. Packing NuGet package from output of native multi targeting build
3. Build Versioning
4. .net Argument validators

This co-mingling is a violation of the "separation of concerns" principle, which is made worse by assuming the same version number for the package on all builds. Since it is only ever locally built one might assume that's not a problem. Turns out it is. NuGet msbuild and VS do lots of information caching etc... that assume the version is locked once published. So things go pear shaped pretty quickly in weird ways. While it is possible to limp along it is far from ideal and would tend to discourage community contributions.

Thus the tasks should be split into separate publishable and versioned packages. The native support (#1 and #2) might remain together because they are both focused on the multi-targeting of vcxproj files. Ideally the package can be applied to an existing vcxproj (with some additional property changes) in a manner similar to how this works for csproj already. Nuget pack would ideally leverage as much as possible from the existing nuget.pack targets so that downloading nuget.exe was not needed.

The versioning support should be isolated to it's own NUPKG and remove any LLVM.NET specifics so that it is re-usable across other projects and is updateable independently. THe LLVM.net specific support (which is pretty much limited to the llvm version and default nuspec properties) Can move to a Directory.Build.targets file

The .net Argument validators are currently only used by the buildTask itself but there are some equavelents in Llvm.NET but without the attributes that keep CodeAnalysis aware of the validation. Thus Llvm.NET has a bunch of suppressions that could be removed in favor of more explicit and simpler arg checks in a consistent fashion. Other applications can also leverage this generic functionality.

Thus the work is:

• Create Argument validators package
• Create Versioning package
  • Update LLVM.NET to use new package and implement LLVM specific support to Directory.Build.(props|targets)
• Create Native multi targeting package
  • leverage existing nuget pack targets or tasks from C# projects or at least use nuget.commandline nugetpkg to get nuget.exe