v0.0.0-beta3

Trampolines! (#236)

The star of the show in this release is the new trampolines infrastructure. "Trampolines" are what we call the tiny functions used to make it easier to call lower-level C/C++ functions.

Biohazrd already generated trampolines for eliminating low-level C++ ABI details, but everything was hard-coded in Biohazrd's emit stage and was not extensible at all. This meant if you wanted to provide your own user-friendly overloads you had to make your own declaration with its own emit logic and make a bunch of assumptions about how Biohazrd would emit your target function.

This new API revamps how Biohazrd emits trampolines entirely. Trampolines are mad up of a set of adapters which define how parameters and return values are mapped between your trampoline and the function they call (which can be either the native P/Invoke or another trampoline.)

Trampolines are created by using another as a template, which means you can chain trampolines together or modify existing ones by simply specifying what you want to change.

You can use trampolines to generalize assumptions about the API you're wrapping to make it easier for your C# consumers to interact with them. For example, you can use them to provide overloads to functions to automatically marshal strings to UTF8 or provide a generic wrapper which passes appropriate GUID to a COM-style factory function.

Check out this Mochi.DearImGui commit to see how the new API improved how it emits its own automatic string marshaling functions.

In order to use trampolines, you must use CreateTrampolinesTransformation in your pipeline, right after AutoNameUnnamedParametersTransformation. This will also upgrade your project to use trampolines for Biohazrd's internal trampoline emit.

Code Gen Improvements

• out byref is no longer used for return buffers, improving performance. (#196)
• Implicit C++ byrefs no longer require explicitly passing by reference in C#. (#79)
• We no longer use MarshalAs for booleans, improving performance. (#237)
  • We either skip emitting it where it wasn't actually necessary and NativeBoolean where it was.
• C++ references in the context of parameters are now emitted as C# ref or in as appropriate. (Previously they were emitted as raw pointers.)
  • This makes passing values to these parameters much simpler and more similar to how things work in C++.
  • See Mochi.DearImGui v0.0.1 or Mochi.PhysX v0.0.0-alpha1 release notes for samples of how this improves things for them.
  • You can also enable it for returned C++ references by setting CreateTrampolinesTransformation.EmitCppReferenceReturnsAsCSharpReferenceReturns, although make sure you understand the caveats on their usability from C#.

Misc

• Biohazrd's tests now target .NET 6. Biohazrd its self targets C# 10. As such, you must have .NET 6 installed to build Biohazrd yourself.
  • Biohazrd will continue to target .NET 5 as long as it remains convenient to do so. However .NET 5 goes out of support in about a month, so you should probably migrate to .NET 6 sooner rather than later.
• Added new features specific to .NET 7
  • DisableRuntimeMarshalling (#233)
• Added workaround for .NET's NullReferenceException not being thrown correctly on Linux. (MochiLibraries/ClangSharp.Pathogen#7)

Deprecated functionality

• Biohazrd's legacy trampoline emit strategy will still be used if you fail to use CreateTrampolinesTransformation, but you should consider this legacy strategy to be deprecated. It will not receive any new development or fixed, and will likely be removed sooner rather than later because it represents a non-trivial amount of code and complexity within CSharpLibraryGenerator.

Upcoming Features

Originally this release was planned to ship the new hosted generator API and Dr. Mochi, but these still need some more time in the oven.

I've also been hard at work on documentation so that generator authors don't need to rely on the other generators I've published to figure out how Biohazrd works.

Special Thanks

Special thanks to my sponsors NeuroGEARS and AnderT. The Mochi Library ecosystem wouldn't have ever gotten this far without your support!