Clang upgraded to 14.0.4 (https://github.com/MochiLibraries/Biohazrd/issues/241)

We now use Clang 14.0.4. (Up from 12.0.1)

This mainly fixes STL1000 errors on Windows with the latest versions of the Microsoft STL. (Clang 13+ is required by the Microsoft STL as of https://github.com/microsoft/STL/pull/2474)

Note that this did cause some very minor codegen changes, most of which are aesthetic and will not affect you.

.NET 5 no longer supported

As a side-effect of the Clang upgrade, we've also upgraded ClangSharp which has dropped explicit support for .NET 5. Additionally, Microsoft dropped support for .NET 5 as of a month ago.

As a result Biohazrd now targets .NET 6, which we intend to support for at least as long as it is supported by Microsoft (which will be until November 2024.)

Please get in touch if this is a problem for you. (Remember this only affects your generators, Biohazrd can still generate code which targets .NET 5. See our platform support documentation for details.)

ClangSharp license changed

ClangSharp is now part of the .NET Foundation. As a side-effect the license and copyright string has changed. (It's now licensed under the MIT License, same as Biohazrd.)

This most likely does not affect you significantly, but please be mindful of how this may affect your legal obligations.

Special Thanks

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

Trampolines! (https://github.com/MochiLibraries/Biohazrd/issues/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. (https://github.com/MochiLibraries/Biohazrd/issues/196)
• Implicit C++ byrefs no longer require explicitly passing by reference in C#. (https://github.com/MochiLibraries/Biohazrd/issues/79)
• We no longer use MarshalAs for booleans, improving performance. (https://github.com/MochiLibraries/Biohazrd/issues/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 (https://github.com/MochiLibraries/Biohazrd/issues/233)
• Added workaround for .NET's NullReferenceException not being thrown correctly on Linux. (https://github.com/MochiLibraries/ClangSharp.Pathogen/issues/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!

It's been a hot minute since a proper published release of Biohazrd! This release primarily focuses on adding some minor nice-to-have features and bug fixes.

Most notably C++ constructors are actually emitted as C# constructors now. (You must target C# 10 for this to work with parameterless constructors.)

New Features

• C++ constructors are now emitted as C# constructors.
• You can now specify a target .NET runtime and C# language versions for generation. (Default is .NET 6 and C# 10.)
• Added basic support for constant declarations. (https://github.com/MochiLibraries/Biohazrd/issues/5)
  • They aren't emitted from initial translation yet, but you can add them yourself. See ImVersionConstantsTransformation for example usage.
• Introduced SimpleTransformation to make it easier to write simple one-off transformations composed of lambda expressions.
• Added new info for macros, you can now get:
  • Whether or not a macro has a value (https://github.com/MochiLibraries/Biohazrd/issues/223)
  • Whether Clang considers the macro to be part of a header guard pattern.
  • The macro's value as a semi-normalized string (This is meant for debugging and reports, please don't try to parse using this! Use TranslatedLibraryConstantEvaluator instead!)
• Added the ability to add extra source code during constant evaluation. (https://github.com/MochiLibraries/Biohazrd/issues/228)
  • This is useful if a macro requires a certain namespace to be in scope, a file to be included, or a certain user-defined type in order to be evaluated.
• Added Linux ARM64 support.
• size_t/ptrdiff_t and similar types are emitted as nuint/nint instead of their underlying type (IE: ulong/long.) (https://github.com/MochiLibraries/Biohazrd/issues/82)

Deprecated functionality

• Clang info dumping has been deprecated. It was broken by recent changes in ClangSharp in all but the most trivial cases. (This was an internal debugging feature that was rarely used. See https://github.com/MochiLibraries/Biohazrd/issues/227)
• CSharpBuiltinTypeTransformation was merged into CSharpTypeReductionTransformation (https://github.com/MochiLibraries/Biohazrd/issues/107)
  • This was an artifact of how the original prototype of Biohazrd worked and was more confusing than useful.

Breaking changes

• The Length member of constant array helpers is now emitted as a property instead of a constant
  • (This makes it more natural and easier to use in real-world code.)

Minor Features & Fixes

• Added warning when a type with virtual methods doesn't have a constructor. (You can't currently instantiate these types from C#. See https://github.com/MochiLibraries/Biohazrd/issues/31)
• Added bare-bones support for generating on macOS x64. (https://github.com/MochiLibraries/Biohazrd/issues/226)
  • macOS is still unsupported as a target platform, see the new platform support documentation for details.
  • If you're interested in macOS support please consider sponsoring development.
• Fixed incorrect/misleading verification around unsupported default parameter values.
• Fixed char being handled incorrectly wheN ResolverTypedefsTransformation isn't used. (https://github.com/MochiLibraries/Biohazrd/issues/232)
• Added using the global namespace as the root namespace to OrganizeOutputFilesByNamespaceTransformation
• Fixed some broken and missing TranslatedDeclaration.ToString implementations

Upcoming Features

The next release of Biohazrd will feature a new hosted generator API which greatly reduces the amount of boilerplate required of generator authors. (Before 🔜 After)

I'm also hard at work on a new tool called Dr. Mochi (pictured below) for helping you debug your Biohazrd generators.

This is a minor release primarily providing bug fixes for Linux and niche features for advanced consumers.

New Features

• You can now query if a file was in-scope but was not actually used during translation using TranslatedFile.WasNotUsed.
  • This can happen if a file was declared as in-scope, not indexed directly, and was never included, making this useful for generating reports for libraries which provide a master include file to detect files which weren't included by it.
  • (This can also happen if a file is effectively empty - such as a file which only contains comments.)

Linux Features

• Kaisa now supports parsing ELF files and Linux-style library archive files.
  • Kaisa is a supporting library for Biohazrd used to power LinkImportsTransformation. (You can read the motivations behind this change here: https://github.com/PathogenDavid/Kaisa/issues/1)
  • This means Kaisa can now parse Linux shared library (.so) files and Linux static library (.a) files
  • What this means for generator authors: Shared library handling for Linux generator is now more robust, advanced consumers can now process Linux static libraries.

Bug Fixes

• Fixed confusing warnings caused by synthesized syntax elements (https://github.com/InfectedLibraries/Biohazrd/issues/216)
• Fixed LinkImportsTransformation emitting errors for virtual methods exported by a static library even when ErrorOnMissingVirtualMethods is disabled
• InlineExportHelper no longer tries to suppress MSVC warnings when generating for Itanium targets.

This is the initial NuGet.org release of Biohazrd.