public API specification files for language bindings maintainers

[martinfouilleul]

Regroup public API in a specification file for language bindings maintainers. The idea is that they should be able to automate most of the bindings, so they don't have to rewrite manually for each change we make on our side. It will also give them a clear view of the API surface to expose in the first place. A simple json format inspired by the wasm bindings spec files we already use internally should be sufficient.

There are a few options to do this:

• Write these by hand. This could be ok for a start, but this puts the burden of manually updating them for each tiny API change on us. As the API evolves this doesn't seem like a viable solution long term.
• Write these by hand and generate our header files from them. This would solve the sync of the specs with the headers, but this kinda forces us to develop our API in these json files, which is pretty annoying. Unless we maintain separate headers for dev and only push changes to the spec when reaching some milestone, and regenerate headers from that, but this means either the spec files are broken most of the time, or we must basically update them each time we commit, which ruins the point.
• Generate the spec files from our header files. C is like the worst language to do this, but this seems like the correct solution once it's in place. As an example, we can look at what raylib does: it parses headers with a custom parser to generate json/xml files. However, this imposes some constraints on their code, and their API is also not really structure heavy. For our case maybe we could use https://github.com/llvm/llvm-project/blob/main/clang/include/clang-c/Index.h (Clang C api) to generate json from our header files.

We can probably start with option one to allow language bindings maintainers (e.g Bill and Skytrias) to start experiment with our spec format. Once they have some automated process in place and the format is solidified we can work towards an automated solution on our end.

[martinfouilleul]

It would also be worthwhile to reorganize our own headers to better split the orca app facing APIs from our native-only ones. This might not always be possible since most APIs are used on both sides, and I don't want to create myriads of tiny files just for the sake of separation either, but at least it's worth exploring what we can do on this front.

[martinfouilleul]

We could also have the API spec files be authoritative, but commit the generated header files, and have a CI job that checks that spec-generated headers match committed headers, and rejects releases (or merging into main?) if it doesn't. This way we can dev on the committed C headers, and integrate our changes to the spec files only before making a release.