Skip to content

Latest commit

 

History

History
122 lines (68 loc) · 10 KB

PlatformSupport.md

File metadata and controls

122 lines (68 loc) · 10 KB
Raw

Platform Support

In short: Biohazrd officially supports generating on and generating for modern versions of the following platforms:

  • Windows x64
  • Linux x64
  • Linux ARM64

If you're interested in other platforms, please consider sponsoring development and getting in touch to register your interest!

Biohazrd deals with low-level C/C++ ABI details, and as such it requires a certain degree of platform support beyond what you might expect as a .NET developer. There are two halves to the platform support coin:

  • Support for platforms you generate on (where you run your Biohazrd generator)
  • Support for platforms you generate for (where you use the library you generated)

The platform you generate on

At its core, Biohazrd is powered by the Clang C++ compiler via a modified version of libclang called libclang-pathogen.

libclang-pathogen is provided by one of the ClangSharp.Pathogen.Native.<rid> packages. Without this native runtime, Biohazrd cannot process your header files.

We currently provide packages for the following platforms:

  • Windows x64 (win-x64)
  • Linux x64 (linux-x64)
  • Linux ARM64 (linux-arm64)
  • macOS x64 (osx-x64) -- Note that macOS is only partially supported, see the macOS-specific section below for details.

With the official Biohazrd NuGet packages, Windows x64 and Linux x64 will work out of the box.

For other platforms you will to manually reference the appropriate native runtime package. (If you run your generator Biohazrd will throw an exception telling you which one to install.) Do note that the native runtime package and the version of ClangSharp.Pathogen used by Biohazrd must match exactly. You will receive a build error if you attempt to mix and match.

Linux distro support

We build our x64 Linux binaries on Ubuntu 18.04 and our ARM64 Linux binaries on Ubuntu 20.04. As such you should be able to run your generator on any Linux distro which uses glibc version 2.27 and 2.31 respectively. You can check the version of glibc on your system using ldd --version.

Note that this requirement only applies to where you run your generator. Your generated library will work anywhere its own native component works, which depends on how you build or acquire it (and is beyond the scope of this document.)

If you're on a system targeting an older version of glibc, you may be able to use the official .NET Docker images, which are currently based on Debian 11 (glibc 2.31.)

If you're interested in having Biohazrd work on older Linux distros, you can register interest in this ClangSharp.Pathogen issue.

ℹ Note that some distros targeting the Raspberry Pi target 32-bit ARM, which we currently do not support. (This includes Raspberry Pi OS/Raspbian unless you're using the ARM64 beta.)

If you aren't sure which architecture your're using, check the output of uname -m (it will print aarch64 for ARM64) or dotnet --info (the RID will end with -arm64.)

Using Biohazrd on unsupported platforms

If you're willing to build libclang-pathogen yourself, you may be able to use Biohazrd on unsupported platforms.

⚠ However, do note that generating for unsupported platforms may have other quirks and caveats. So make sure to read the section on that below.

You can build libclang-pathogen using the instructions in the ClangSharp.Pathogen repo. (Take care to build using the same version of ClangSharp.Pathogen used by the version of Biohazrd you're using. The build-time version compatibility check does not apply when using a custom native runtime.)

In order for Biohazrd to pick up your custom runtime, you need to provide it:

  • Set the BIOHAZRD_CUSTOM_LIBCLANG_PATHOGEN_RUNTIME environment variable as the path to your self-built runtime.
  • Call ClangSharp.Pathogen.LibClangSharpResolver.OverrideNativeRuntime with your self-built runtime.

(Either of these must be done before the first call TranslatedLibraryBuilder.Create.)

The platform you generate for

Biohazrd officially supports generating wrappers targeting the following platforms:

  • Windows x64
  • Linux x64
  • Linux ARM64 (Alpha)

Outside of those well-tested options you may be wandering into uncharted waters.

C libraries should typically be fine since .NET has strong support for them through P/Invoke, but C++ libraries can occasionally become dangerous territory.

Because .NET does not support interop with C++ directly, you're relying on Biohazrd to handle all the grisly C++ ABI details on your behalf. In turn we rely on Clang to tell us how to handle the majority of this correctly, but things do occasionally slip through. Debugging these issues can get very complicated and is not for the faint of heart.

In addition to Biohazrd's handling of ABI concerns, some features of Biohazrd require understanding of the platform's build system. In particular, LinkImportsTransformation requires knowing how to link to dynamic libraries on your target platform. Internally it uses Kaisa the Sharp Librarian, which currently only supports handling Windows and Linux libraries. (For simpler libraries you may not need these features, but it's worth knowing about.)

.NET runtime support

Biohazrd its self is a .NET 6 library, so generators themselves must target .NET 6 or newer. We intend to support .NET 6 for as long as it is supported by Microsoft. (.NET 5 support was dropped in v0.0.0-beta4.)

As for the wrappers you generate with said generators, Biohazrd is not especially opinionated about the version of the .NET Runtime you target, but it does prefer generating C# 10 code. (C# 9 if you ask nicely.)

Officially speaking, C# 10 is only supported for use with .NET 6 (and C# 9 with .NET 5.) That being said, newer versions of C# tend to work just fine on older versions of .NET as long as you don't utilize any new runtime features and the C# compiler is good about letting you know at build time if you accidentally do.

We generally recommend sticking to .NET 6 (or newer) if you can. You can indicate the .NET runtime and/or C# language version you're targeting via CSharpGenerationOptions.

If you must target older framework, we recommend building your generated library with the .NET 6 C# compiler with C# 10 and targeting the framework you need. Please keep the following caveats in mind:

  • Native libraires featuring function pointers on their API surface require the use of C# 9 function pointers. Depending on the context, you may not be able to utilize these APIs at all on older runtimes without extra effort.
  • For C++ libraries, parameterless constructors (including ones which are defined implicitly by the compiler) are handled using C# 10 parameterless struct constructors by default. These constructors work just fine when called normally (even from old C# compilers), but they have major issues when called by reflection or in a generic context. (See dotnet/runtime#6536 and dotnet/runtime#45397)

Notes on specific platforms

x86 (as in 32-bit)

Biohazrd does not support 32-bit x86 and is not tested with 32-bit x86.

C libraries likely work just fine as long as you pass the appropriate target triple via TranslatedLibraryBuilder.AddCommandLineArgument.

If C++ libraries work, it's purely by accident. There are certain dark corners of C++ x86 ABIs which require further investigation and may be impossible for Biohazrd to handle without significant effort. (When Biohazrd encounters these situations, it will likely emit an error at best or invalid codegen at worst.) Our general attitude is that 32-bit x86 is legacy and you should target x64 instead. It is unlikely much effort will be invested into Biohazrd supporting x86 without significant sponsorship.

macOS

Currently there is no financial backing behind macOS support of Biohazrd. We build ClangSharp.Pathogen's native runtime for macOS x64, but very little work has been done verifying Biohazrd's operation on macOS.

We do not have access to any Apple Silicon hardware for development or CI purposes, as such Biohazrd cannot realistically support it. You may be able to use Biohazrd on Apple Silicon devices via Rosetta 2.

If you're interested in using Biohazrd in conjunction with macOS, please consider sponsoring Biohazrd development.

Windows on ARM

We do not have access to any Windows on ARM hardware for development or CI purposes, as such Biohazrd cannot realistically support it.

You might be able to use x64 emulation with Windows 11 or Windows 10 Insider.

If you're interested in using Biohazrd in conjunction with Windows on ARM, please consider sponsoring Biohazrd development.