Comparing to SWIG

[rokups]

Hey!
After reading your message i am very intrigued by your project! I myself maintain a project (game engine) of considerable size which has C# bindings. Road was long and complicated. I tried rolling my own bindings generator. I tried CppSharp. I finally ended up using SWIG. It is a great project, but age really shows, and when it comes to a point where extra features are needed - there is no support and i hate every second working with SWIG codebase. Something better would be nice and Biohazrd looks like something much better! Lack of C layer is especially exciting! CppSharp also avoids C layer, however i had quite a hard time with it. Biohazrd seems to have a potential to accomplish the task much better and we would love to switch if we could cover all our bases. And i would not mind contributing my time towards the project now that i would not have to fix SWIG ;)

So i have some questions (and maybe answer could end up in readme as a feature table) as i have not found a detailed list of supported features. Here is a list of things i have encountered wrapping a non-trivial project:

1. Object lifetime. This is a complicated topic. How does Biohazrd handle it? There are several different cases, would be great if wrapper could handle them mostly transparently. I suppose it is mostly manual, but sometimes we need more.

My project extensively uses intrusive refcounting by storing C# object handle in the native class in order to prevent garbage collection of managed instance if user loses all references to it. Engine may keep a native reference alive, and managed object may be providing logic implementation via overriden virtuals. This is achieved by inserting some custom logic at the points where C++ pointer is getting translated to C# object and in Dispose()/Finalize(). Good thing about all of this is that we can always return same C# object for a certain C++ object pointer, by fetching it from object handle stored inside C++ object. A natural consequence of this is that we can mark C# object as "expired" if native side frees last reference and deallocates C++ object. Unity works this way AFAIK.

Another important machinery i implemented is caching of C# object instances. This is required for non-refcounted objects since there is no space to store handle of managed object in them. This is important, because we use event handlers that take a hashmap as a parameter. Such handlers get called many times per frame and we can not afford allocating a new C# wrapper object for same hashmap pointer many times per frame. This is implemented same way like refcounted object customization - injecting logic at T* -> C# object translation and Dispose()/Finalize().

Is it possible to do such custom code injections to customize how wrapper works?

2. Templates. In my experience it is enough if we could generate unique wrappers for each template class instantiation. However this would require generating an additional .cpp file which explicitly instantiates these templates. Maybe a similar technique would work for functions that dont get code generated (inline for example)? This is closely related to wrapping native containers. SWIG does it quite nicely by making native interface private, and injecting a public C#-like interface, so wrapped containers inherit IEnumerable<> and everything.

3. Implementing certain types manually in C#. For performance reasons we have some classes implemented straight in C#, to avoid paying a cost of crossing managed/native boundary each time method is called. Can we do this for our own types?

4. Strings! Oh i hate strings. How is Biohazrd dealing with them? Not only we need to translate utf-8 string to whatever C# uses (and that costs), but we also need to handle:

   • std::string&
   • const std::string&
   • const char*
   • char* would also be nice
   • functions that return newly allocated char* and it is user's responsibility to free it

5. Function pointers. Any support for those?

6. Virtual method overriding. I saw vtables are generated, which is great. I did not see if we can override them. I only looked a bit at physx wrapper though.

7. Are operators handled at all?

8. Any support for arrays? (Both as func parameter and as field in an object).

9. Default function parameter values? SWIG generates overloads. My custom bindings generator did a mix of Nullable<> + naive parsing of default value expression strings. Now that i think of it, these native expressions could totally end up in a .cpp function and get returned.

10. What about static constants of complex type? For this once again seems like .cpp returning constant would be required.

11. Forgot multiple inheritance. SWIG generates interfaces for classes used as a second+ base. This introduces some restrictions to other steps (like hiding getters/setters for of generated properties if a class inherits from interface). Another important detail is that SWIG keeps a C++ pointer to each base. Biohazrd probably knows how to upcast without going through C++? This was possible in CppSharp at least.

There are many more things we need, but from bird's eye view it seems like Biohazrd already handles them, or at least should, given how its implemented. Thank you for working on this, world really needs a good and modern bindings generator.

[PathogenDavid]

I myself maintain a project (game engine)

Looks cool!

I do mention this later on, but I did want to mention up front that the focus for Biohazrd has been the .NET 5 CoreCLR runtime. This is partially due to the fact that it uses C#9 function pointers, which officially-speaking are only supported on .NET 5. If I am remembering correctly, some bugs in CoreCLR around CLI function pointers had to be fixed. (The feature already existed within the CLR to support C++/CLI and the internals of delegates, but was never exposed in C# until recently.)

I bring this up since I saw you're using Mono. I have 0 clue what the situation is with Mono, but there is a chance that could be a problem. Mono is a bit of a dead end though, so maybe this is a good excuse to replace it with CoreCLR? 😁 (I know, big ask. Plus I've heard CoreCLR is harder to embed compared to Mono, but hey maybe the added performance benefits make it worth it.)

As I note below, Biohazrd could potentially be retooled to use delegate-marshaled function pointers, but those have a bunch of problems and don't jive well with Biohazrd's architecture.

I tried CppSharp. I finally ended up using SWIG. It is a great project, but age really shows

Yup, I'm familiar with that mood. I tired both before creating Biohazrd.

And i would not mind contributing my time towards the project now that i would not have to fix SWIG ;)

Would definitely love to have you! Every passing day I'm worried Biohazrd is way too "me" and as much as I love using it, I want a framework that benefits everyone not just me. I've had a handful of other people put eyes on it, but I'm still the only one who's made substantial use of it.

and maybe answer could end up in readme as a feature table

I definitely need to spend more time on documentation, will definitely use this conversation and those on imgui_private to inform areas I should focus on.

Object Lifetime

1. Object lifetime. This is a complicated topic. How does Biohazrd handle it? There are several different cases, would be great if wrapper could handle them mostly transparently. I suppose it is mostly manual, but sometimes we need more.

So the answer currently is...it kind-of doesn't? Not to say I haven't thought about it, it's more that Biohazrd takes a different approach to this issue than SWIG or CppSharp do.

As you've noted, there's no one-size-fits all approach for handling the relationship between managed and unmanaged object lifetimes. Biohazrd does not attempt to try and prescribe a specific philosophy because no matter what that philosophy would not work well for everyone.

A good example is Direct3D. A dictionary associating the unmanaged identity to a managed identity would be unecessarily inefficient here because it'd make a lot more sense to just store a GCHandle in the ID3D12Object's private data.

Similarly, in Direct3D 12 the lifetimes of objects needs to be carefully considered so it doesn't really make sense to try and add garbage collection capabilities to the managed identity of D3D12 objects. Conversely though, Direct3D 11 is much more liberal about object lifetimes and the driver handles most of it for you, so allowing a D3D11 object to be released when the managed identity is collected might be desirable.

Another important thing to consider is that different abstractions have different performance characteristics. For instance a tiny wrapper struct that just hides the C++ pointer is basically free, whereas a fat object with a finalizer makes allocating the managed identity of an object much more expensive: (Source for this benchmark)

Method	Mean	Error	StdDev	Gen 0	Gen 1	Gen 2	Allocated	Code Size
NoFinalization	4.153 ns	0.0727 ns	0.0645 ns	0.0076	-	-	32 B	47 B
WithFinalization	973.194 ns	9.5370 ns	8.9209 ns	0.0076	0.0038	-	32 B	47 B
SafeHandle	970.385 ns	9.7822 ns	9.1502 ns	0.0076	0.0038	-	32 B	47 B

Plus certain designs for the managed identity enable different capabilities which may or may not be important depending on the library. A good example here is the `ManagedLoggerBase in InfectedTensorRT -- That repo is still private so check your email for access. That type allows a managed C# object to inherit from a C++ class and override its virtual methods. All that boilerplate can add cost and this extra type adds noise to the API surface, so in cases where it will never be used it doesn't make sense to generate it for no reason.

(As an aside, I want to note that InfectedTensorRT's output is mega jank because it uses a dirty hack to add namespaces from before Biohazrd supported namespaces.)

Biohazrd's philosophy

My general philosophy for interop libraries is that they should be done in two distinct layers:

• The unsafe layer. (No classes, everything is structs. Lots of pointers. You're in the weird twilight zone between managed C# land and unmanaged C++ land. You can do anything you can do with C++.)
• The safe layer. (Customized for the specific library being wrapped. This is usually a mix of manually and automatically generated code.)

The main reason why I think this distinction is important and that having both available is important is that well-meaning safe layers routinely inhibit certain capabilities of an API. One example I've seen prevalent in a lot of interop libraries are APIs which take pointers that can be null to indicate that parameter shouldn't be used. These types of APIs are (generally) only discoverable by reading the documentation, so safe interop layers almost always miss a few.

Sometimes the lines can blur a little bit where the safe(r) helper methods are emitted alongside the dirty unsafe methods. For example, here's what my private Direct3D12 wrapper generates for D3D12CreateDevice:

[DllImport("d3d12.dll", CallingConvention = CallingConvention.Cdecl, EntryPoint = "#101", ExactSpelling = true)]
public static extern HRESULT D3D12CreateDevice(IUnknown* pAdapter, D3D_FEATURE_LEVEL MinimumFeatureLevel, in Guid riid, void** ppDevice);

[MethodImpl(MethodImplOptions.AggressiveInlining), DebuggerStepThrough, DebuggerHidden]
public unsafe static HRESULT D3D12CreateDevice<TD3D12Device>(IUnknown* pAdapter, D3D_FEATURE_LEVEL MinimumFeatureLevel, out TD3D12Device* ppDevice)
    where TD3D12Device : unmanaged, IID3D12Device
{
    TD3D12Device* __ppDevice;
    HRESULT __returnValue = D3D12CreateDevice(pAdapter, MinimumFeatureLevel, IUnknown<TD3D12Device>.InterfaceId, (void**)&__ppDevice);
    ppDevice = __ppDevice;
    return __returnValue;
}

[MethodImpl(MethodImplOptions.AggressiveInlining), DebuggerStepThrough, DebuggerHidden]
public unsafe static TD3D12Device* D3D12CreateDevice<TD3D12Device>(IUnknown* pAdapter, D3D_FEATURE_LEVEL MinimumFeatureLevel)
    where TD3D12Device : unmanaged, IID3D12Device
{
    TD3D12Device* __ppDevice;
    D3D12CreateDevice(pAdapter, MinimumFeatureLevel, IUnknown<TD3D12Device>.InterfaceId, (void**)&__ppDevice).ThrowIfFailure();
    return __ppDevice;
}

Basically I've taught my generator to recognize the REFIID, void** factory method pattern prevalent in Direct3D 12 and make these little wrapper methods that make them easier to use correctly, but the unpleasant, raw version is still available. (Although you will note I also taught it that the Guid parameter should be an in reference since that's a safe generalization to make for REFIID.) Obviously all three of these functions require unsafe code in C#, but the latter two are easier to use "correctly".

How Biohazrd helps with the managed interop layer

Currently Biohazrd focuses on that unsafe layer, but enables you to augment generation to generate the safe layer.

The plan is that eventually Biohazrd will ship with some common patterns and/or provide guidance on how to generate your safe interop layer. (For instance, Biohazrd could pretty easily generate a ManagedLoggerBase-shaped object for all classes with virtual methods.) It is already very easy to make generalizations about your API and generate suitable safe wrappers for them. (Although there are still some pitfalls I want to address.)

Is it possible to do such custom code injections to customize how wrapper works?

To answer this question directly: Yes. You do it using custom declarations. I don't have any great examples in a public generator, but here's the one used for that previous Direct3D 12 factory pattern example. (Apologies that example references some stuff not in this repo. I haven't finalized the shape of things like ManuallyImplementedTypeDeclaration so they aren't published yet.)

Templates

2. Templates. In my experience it is enough if we could generate unique wrappers for each template class instantiation. However this would require generating an additional .cpp file which explicitly instantiates these templates.

The story around templates is definitely still evolving as none of the current target libraries make heavy use of them except for OpenCV. Biohazrd still mostly leans on the generator author to decide how they will be translated to C# and doesn't provide much help in doing so.

In my experience templates come in a handful of shapes:

1. Generic functions
2. Generic POD types
3. Generic classes

Loose generic functions are not handled at all right now out of pure virtue that they haven't been needed yet. As you note, these will likely just involve shoving them into an additional .cpp file to explicitly instantiate them as needed.

Generic POD types fall into two categories depending on whether or not they can be represented by .NET generics. If they can, ideally you would just make them C# generic structs so they're just as nice to work with in C# as they are in C++. This mostly just depends on whether they use numeric constants as template parameters. (Think of a matrix type with arbitrary dimensions.)

Biohazrd contains some very experimental support for automatically instantiating all implicit template instantations and generating types for them. You can see hints of this in this test, and here's an example from OpenCV where a templated Rect struct was instantiate with both ulong and uint arguments. (Names are jank due to a quirk in how Biohazrd processes the typedefs which should name those types.)

Finally there's those generic classes. Which are basically a combination of both.

As noted earlier, some templates can be represented in C# as generic types. A good example of this is the ImVector<T> template, which I decided to manually translate to C# and have the generator replace references to it with my manually implemented type. I've had thoughts on doing a heuristic-based translation of these sort of types, or generating a skeleton type with all data and no methods, but none of that has been realized. (Translating method bodies to C# is obviously an ordeal for anything but the most trivial templated types.)

Eventually I'd like it so that Biohazrd will automatically instantiate all of the implicitly instantiated templates and expose them as rigid types in C# with the option for the generator author to replace them with something more friendly as I did with ImVector<T>.

Inline functions

Maybe a similar technique would work for functions that dont get code generated (inline for example)?

Yup, this is basically how Biohazrd handles inline methods today. Here's an example from InfectedPhysX. (Taking a pointer to an inline function causes it to be included in the DLL thanks to a convenient technicality in the C++ spec stating that function pointers to inline methods must all be the same.)

Wrapping STL containers

This is closely related to wrapping native containers. SWIG does it quite nicely by making native interface private, and injecting a public C#-like interface, so wrapped containers inherit IEnumerable<> and everything.

Edit: I noticed after writing all of this that you're using EASTL. If you use it everywhere that Biohazrd would be involved, that may simplify things since it's not as much of a moving target as whatever arbitrary STL gets picked up by whatever C++ compiler was used to build the project.

As you've probably gathered, Biohazrd does nothing special to make life with STL containerrs tolerable/usable, but this is definitely something I'd like to do whenever I get around to them. I already do something similar for the generated constant array helpers. (I know there's some evil things happening in that code that assume the constant array types never get thrown on the managed heap, it's on my mental roadmap. Ideally they'd be ref structs. Once upon a time they were, I forget why they aren't anymore.)

Manual implementation

3. Implementing certain types manually in C#. For performance reasons we have some classes implemented straight in C#, to avoid paying a cost of crossing managed/native boundary each time method is called. Can we do this for our own types?

Yup! Biohazrd is designed to allow pretty arbitrary manipulation of the declaration tree. Going back to the ImVector<T> example again, the InfectedImGui generator contains this transformation which removes the ImVector declaration. (Ideally it'd actually replace it with a dummy declaration that represents the manaually implemented declaration, but the InfectedImGui generator predates this concept so the ImVector<T> references are fixed up later by ImGuiCSharpTypeReductionTransformation.

Another example of this is that in my private InfectedWin32 wrapper, I manually define this type for ATOM, which is normally just a unsigned short:

using System;

namespace InfectedWin32
{
    public readonly struct ATOM
    {
        private readonly UInt16 Value;

        private ATOM(UInt16 value)
            => Value = value;

        public static explicit operator UInt16(ATOM atom) => atom.Value;
        public static explicit operator ATOM(UInt16 value) => new ATOM(value);

        // Some functions like UnregisterClassW or CreateWindowExW can take a class name char* or an ATOM. This makes it easier to use those APIs.
        public unsafe static implicit operator char*(ATOM atom) => (char*)atom.Value;
        public unsafe static explicit operator ATOM(char* value) => new ATOM(checked((UInt16)value));

        public bool IsValid => Value != 0;

        public static readonly ATOM Zero = new ATOM(0);
    }
}

Within the InfectedWin32 generator I have a transformation which simply replaces the ATOM typedef with a dummy representing this type and all references to that typedef just automagically point to that type instead of being reduced to ushort.

Strings!

Strings! Oh i hate strings. How is Biohazrd dealing with them? Not only we need to translate utf-8 string to whatever C# uses (and that costs), but we also need to handle:

Same.

This sort-of fits into the safe interop layer situation I mentioned where Biohazrd doesn't do a whole lot to help you out yet.

char* and wchar_t*

In the unsafe interop layer, char* is emitted as byte* and wchar_t* is emitted as char* since .NET uses UTF16 strings.

Ideally convienence wrappers should be generated with automatically handle the encoding conversions and memory pinning for you, but I haven't gotten around to doing this with anything yet. Dear ImGui is the main desire here and it uses UTF8 while .NET uses UTF16. I've been secretly hoping either UTF8 in .NET or the ImStr improvements along with the potential optional UTF16 support in Dear ImGui would land before I had to properly address it. (Not a realistic hope, I know.)

In the meantime for ImGui I've been using this helper class which semi-inefficiently lets me quickly re-encode and get a pinned pointer to a string. (Here's an example of it in use.)

std::string

InfectedOpenCV is the first place where this has been an issue, and the wrapper for it started being usable a few weeks ago.

My hope is that eventually a proper C# implementation of std::basic_string can be made to make working with std::string and related types elegant from the C# side of things.

I briefly tested this with InfectedOpenCV, but found that the memory layout and implementation of basic_string is quite a bit more complicated that I thought. (For some reason I remembered it just being a pointer + count pair, but it's more complex than that.) So I ended up making a quick C++ helper that allocates std::string on the heap from a char* pointer:

#define PATHOGEN_EXPORT extern"C" __declspec(dllexport)

static_assert(sizeof(std::string) == 32, "sizeof(std::string) expected to be 32! (Accidentally building debug build?)");

PATHOGEN_EXPORT std::string* AllocateString(const char* value)
{
    std::cout << "Allocating string '" << value << "'" << std::endl;
    return new std::string(value);
}

My current plan is that before I go through the effort of trying to understand the template mess is to read the C++ spec on basic_string to see if it prescribes a specific memory layout for it or not. If it does I'll continue my investigation of a manual C# implementation of basic_string. If it doesn't, I'll probably end up making a native helper to aid in allocating and deallocating them. I'd rather not do this if I don't have to, but as I'm sure you're aware the STL types are very problematic for interop in general.

Function Pointers

5. Function pointers. Any support for those?

First class! They do use C#9 function pointers though. This does somewhat unfortunately imply infected libraries always target .NET 5 as there were some runtime-side fixes made for CLR function pointers. (My understanding is they'll work in downlevel .NET Core since they were used by C++/CLI, but there are some bugs and I forget exactly what they are.)

In theory it's possible to add support for the legacy delegate-wrapped function pointers, but I'd kind-of rather not becuase they're inefficient and a huge pain to properly deal with. (They aren't so bad for functions passed as parameters, but they're downright nasty to deal with when it comes to virtual method tables.)

Virtual method overriding

6. Virtual method overriding. I saw vtables are generated, which is great. I did not see if we can override them. I only looked a bit at physx wrapper though.

Yup! I'm still forming the recommended shape for handling this, but here are some examples:

Here's an example of PxErrorCallback being implemented manually in C#: ErrorCallback.cs.

Here is a (previously linked) managed base class wrapper to make it easier to implement TensorRT's ILogger interface, and here's an example of it being implemented.

Operators

7. Are operators handled at all?

Currently they come through as boring methods. Eventually I want to have them emitted as proper operator overloads when possible

Here's an example of the operators on ImVec2.

Arrays

8. Any support for arrays? (Both as func parameter and as field in an object).

This is indirectly answered above, but constant arrays are translated as special helper types and other arrays are translated as pointers.

Ideally you'd want to generate safe wrappers that take proper .NET arrays and handle pinning them and passing the length to the appropriate parameter and such.

Constants

9. Default function parameter values?

For true compile-time constants (whether they be literals or expressions) Biohazrd will use Clang to perform constant folding and get the value, which will be represented as one of the ConstantValue types. You can see some examples of the constant values which Biohazrd will handle int the DefaultArgumentValueTests.

By default, Biohazrd will emit these values as C# default argument values where possible. When it isn't possible, Biohazrd currently emits a warning and removes the default.

The eventual plan is to have an option to automatically generate overloads for non-defaultable paramaters or maybe using Nullable<T> as you said.

For non-compile-time constants (like with ImGui::Button) I need to do some investigation to determine how much Clang can help us here. It'll probably end up being that we'll heuristically parse the AST for the default argument value and if it's simple enough emit it as an overload.

10. What about static constants of complex type?

Static constants are currently a bit of a blind spot out of lack of need. (Biohazrd doesn't handle them correctly and emits a warning, if I remember right.)

They're in the same situation as default argument values though, so they can be emitted either as true C# constants or static readonly fields/properties.

For this once again seems like .cpp returning constant would be required.

As noted earlier we primarily use Clang functionality for folding constants, but this is actually sort-of how arbitrary macros an expressions are evaluated.

Inheritance

Multiple inheritance

11. Forgot multiple inheritance.

Currently unsupported. If a class has multiple bases an error is emitted and the class will not be usable. The ABI concerns here get real messy really fast and none of our current target libraries use multiple inheritance anywhere.

I've had this mentally filed under "Deal with it when it becomes an issue."

If a library only barely used multiple inheritance I'd be very tempted to just say "screw it" and make a C wrapper just for that type.

(All the information requires to handle it is still processed and present, so a sufficiently sophisticated generator could still piece together the bits and pieces associated with multiple inheritance and handle it on their own or convert the class to a C wrapper.)

Virtual inheritance

You didn't ask, but virtual inheritance (as in that weird C++ feature everyone forgets about) is in the same situation.

Simple inheritance

Biohazrd probably knows how to upcast without going through C++?

Kind-of sort-of. Since the unsafe interop layer is all done with C# structs, there's not any typical inheritance in the C# object model due to the fact that C# doesn't support struct inheritance.

Instead, the default behavior is that base types are represented as a field of that type. So for types allocated on the stack or managed heap, "casting" is just accessing that Base field.

Implicit conversion operators could be created to handle this for you, but I haven't gotten around to it.

If you have a pointer to the type, you unfortunately have to cast it manually or via a reference to that base field. Eventually I'd like to have a Roslyn analyzer which ensures the cast actually makes sense and emits an error if it does not.

I've also been experimenting with pseudo-inheritance in InfectedDirectX using interfaces to represent inheritance relationships, primarily to support those generic methods I've shown a few times:

public partial interface IID3D12Device : IID3D12Object { }
public partial interface IID3D12Device1 : IID3D12Device { }
public partial interface IID3D12Device2 : IID3D12Device1 { }
public partial interface IID3D12Device3 : IID3D12Device2 { }

If you were to generate proper managed identities for your C++ objects using classes you'd be able to represent inheritance as you normally would in C#. If you generated them as handle structs instead (something I've been meaning to try) you could represent the relationships with overloaded implicit/explicit cast operators.

I've been meaning to explore reading RTTI when it's available for proper runtime-checked downcasting but haven't gotten around to it.

This is another area where library-specific decisions can make more sense than trying to create a one-size-fits all solution. For instance, with DirectX you'd likely want to use IUnknown::QueryInterface and with PhysX you'd want to use PxBase::getConcreteType to validate casting.

Closing and miscellaneous thoughts

Thank you for working on this, world really needs a good and modern bindings generator.

Thanks, that's the idea!

Hopefully I didn't scare you off with the underdeveloped safe interop layer side of things. 😅

Also more than happy to hop in a call on Discord or Teams if you have questions that are harder to deal with over text.

[PathogenDavid]

That looks like you're mixing an older version of Biohazrd with a newer version of ClangSharp.Pathogen. LibClangSharpResolver replaced __HACK__InstallLibClangDllWorkaround. If you have both they'll just fight with eachother.

If you were trying to build InfectedImGui, it was still using a version of Biohazrd that was the revision before the switch. I just pushed it up to the latest.

[rokups]

That was the case. And now im stuck with even weirder issue. objdump -T build-linux/lib/libclang.so|grep pathogen_GetTypeSizes returns no results. However if i grep -rF pathogen_GetTypeSizes - can see this function is implemented in clang. Any idea why that would be? I just ran build-native.sh 👀

[PathogenDavid]

Oops, it turns out libclang handles exports differently depending on whether it's build for Linux or Windows so none of my functions were being exported. (Not surprising in retrospect, just didn't think about it.)

I added a workaround in MochiLibraries/llvm-project@f285aee / MochiLibraries/ClangSharp.Pathogen@a0f1e9b and filed MochiLibraries/llvm-project#3 to investigate negative effects the workaround might have and/or properly fix it later. (Chances are I'll add everything to the exports file once ClangSharp.Pathogen has some unit tests.)

You should be able to just update to the latest ClangSharp.Pathogen and re-run build-native.sh. (Don't forget to update submodules too.)

[rokups]

Thanks! It finally worked-ish!

At last i bumped into real no-other-than-windows-platform-support issue. I see generator intends to use a .lib file. Could you tell me how that fits together with source parsing? Is it for verifying whether certain symbols are already exported from .dll?

[PathogenDavid]

worked-ish!

-ish because it's a workaround or ish because you had to fix something? 😅

Could you tell me how that fits together with source parsing? Is it for verifying whether certain symbols are already exported from .dll?

LinkImportsTransformation has a handful of responsibilities, but the primary one is that it identifies which DLL exports which symbols. (As the name suggests, it really is literally a linker.)

Before it was introduced, you had to manually specify what DLL exports each symbol. (Here's an example from an older InfectedImGui.) This is pretty trivial for a lot of libraries (like Dear ImGui), but for more complex ones like the Win32 API or PhysX it makes a lot more sense. (Does this function come from Kernel32.dll? User32.dll? Imm32.dll? Shcore.dll? This gets even more obnoxious if you need to care about API sets in Windows 10.)

As an added bonus, it lets you know if a symbol was actually exported by the libraries you specified. This turns out to be pretty convenient since otherwise you wouldn't know until the the export was actually used at runtime because the .NET Runtime is extremely lazy about initializing P/Invokes.

As an added added bonus(?), if you tell it to add errors to any declaration which wasn't resolved, they will be removed by BrokenDeclarationExtractor so the broken methods/variables won't even be there to distract you. (This obviously isn't the most friendly for a library consumer if the errors were ignored by the generator author. The plan is eventually they will still be emitted but will be marked by [Obsolete].)

For now you can just skip LinkImportsTransformation. If you don't do anything, all exports will be marked as coming from TODO.dll, or you can specify a DLL using a transformation similar to the previously mentioned ImGuiDllNameTransformation.

(The reason for the TODO.dll is that in the past I used NativeLibrary.SetDllImportResolver to override TODO.dll with the actual DLL at runtime. Eventually Biohazrd should be less forgiving if you don't tell it how to resolve exports, but it's also a mistake you catch pretty quickly.)

The plan for Linux is to eventually have LinkImportsTransformation be made aware of resolving exports from a .so just like any Linux-friendly linker would.