This is an exploration/attempt to reorganize the bindings based on DLLs rather than only organizing everything based on the hierarchy established by the upstream metadata project. The "metadata project hierarchy" is a layer on top of an already existing grouping of functions that the OS has already established. With ideas to add filtering, making the code generator aware of this lower level organization will give more fine-grained control and dependency aware filtering mechanisms.
Here's the current idea on how to accomplish this:
New Code Generator Flow
Pass 1: Separate Functions into DLLs and associate types/constants
ForEach API File:
ForEach Function:
append function JSON to <dll_name>.json
Close all currently open JSON files
TODO: should we log somewhere all the DLLs that every API contained functions for?
While generating the DLL json files, store an association between all types and the DLL's that reference them in memory. Once finished, write these associations to an extra file for pass2 to use (i.e. types.json).
Note that "COM objects" are included in these "types". They are not associated with DLL's like functions are, but, there might be functions that come from DLL's that can accept/return COM objects. These interactions will be captured by the type associations we already established above.
Also note that the metadata project has defined special types for some constants, and we can use those types to know where these constants go. However, we may need to do some "finagling" for constants where this hasn't been done, namely, codify the patterns Microsoft has established to organize the constants and use those to find their "home".
Pass 2: Generate Zig
For each <dll_name>.json
open types.json: look at the entry for this dll, and it should list
all types that we need to pull in.
As we are pulling in types, if that type is ONLY referenced in this DLL, then
we generate the definition, otherwise, we generate an import.
Where should we put the definition if it's referenced in multiple dlls?
Option: put all common definitions into 1 giant file!
Option: use "the dll set" as a new file? Maybe we have a manual configuration
file to name these dll sets? For example, if a type is in d3d and d2d, maybe we put it in dx?
TODO: do something for constants
then generate all the function signatures
The Metadata Project Hierarchy
If we like, it should be easy to maintain the existing hierarchy by generating files that link to the corresponding constant/type/function in the newly organized files. This could even be an optional separate package so that new projects don't need to download this large set of aliases if they don't need them.
Filtering
To summarize the reorganization, the generator does this:
Go through each DLL
Go through each function and generate bindings for them
Import/Define every type/constant that each function uses
With this new organization, filtering becomes simple:
Go through each DLL (apply DLL filter)
Go through each function and generate bindings for them (apply function filter)
Import/Defined every type/constant that each function uses (apply type/constant filter)
This is an exploration/attempt to reorganize the bindings based on DLLs rather than only organizing everything based on the hierarchy established by the upstream metadata project. The "metadata project hierarchy" is a layer on top of an already existing grouping of functions that the OS has already established. With ideas to add filtering, making the code generator aware of this lower level organization will give more fine-grained control and dependency aware filtering mechanisms.
Here's the current idea on how to accomplish this:
New Code Generator Flow
Pass 1: Separate Functions into DLLs and associate types/constants
While generating the DLL json files, store an association between all types and the DLL's that reference them in memory. Once finished, write these associations to an extra file for pass2 to use (i.e.
types.json).Note that "COM objects" are included in these "types". They are not associated with DLL's like functions are, but, there might be functions that come from DLL's that can accept/return COM objects. These interactions will be captured by the type associations we already established above.
Also note that the metadata project has defined special types for some constants, and we can use those types to know where these constants go. However, we may need to do some "finagling" for constants where this hasn't been done, namely, codify the patterns Microsoft has established to organize the constants and use those to find their "home".
Pass 2: Generate Zig
The Metadata Project Hierarchy
If we like, it should be easy to maintain the existing hierarchy by generating files that link to the corresponding constant/type/function in the newly organized files. This could even be an optional separate package so that new projects don't need to download this large set of aliases if they don't need them.
Filtering
To summarize the reorganization, the generator does this:
With this new organization, filtering becomes simple: