[Discussion] Simplify custom bindings generation for custom builds

[rminderhoud]

Hello, I just wanted to make a small proposal to this wonderful crate. Namely, to improve the ergonomics for when using a custom build of godot.

Problem
The problem is as such, a user wants to use godot-rust with a custom build of godot so they need a custom build of gdnative-bindings to use godot-rust. The current process is nicely documented here but it is quite convoluted. To summarize, when using a custom godot build we need to rebuild the gdnative-bindings with the correct api.json exported from our custom godot build. The recommended steps are to download the gdnative-bindings crate, modify the stored api.json file, and then do some magic in our project's Cargo.toml.

Criticism
My main argument against this implementation is that it's neither here, nor there. On the one hand, there's the kind of user that is comfortable customizing godot, making a custom build, using these bindings, etc. For those people I think we can safely assume that they would be comfortable maintaining a fork of this repo and can simply change the api.json directly. For these power users, I would argue the guidance can be simplified to "regenerate the api.json here and rebuild".

On the other hand I think there is a second type of user who uses a custom build of godot but maybe makes very minor modifications (disable specific modules, compiler tweaks, etc.) or none at all (e.g. is on a minor version beta). For this user I think the steps outlined in the docs are too cumbersome. If I am on 3.2.3-stable but I want to test my project on 3.2.4-beta then there's quite a bit of ceremony to update my gdnative lib.

Proposal
I believe we can simplify the process by leveraging the build file in gdnative-bindings. I propose that using a feature flag and an environment variable, the api.json can be automatically generated at build time. This would allow users to use the latest sources without having to modify any source code but still be able to target a custom build. Here is an example of how I would foresee this working.

A new feature flag would be introduced in the top level crate that gets forwarded to the gdnative-bindings crate. Users who want to use a custom build would specify this feature flag.

[dependencies.gdnative]
version = "0.9.1"
features = ["godot_custom_build"]

The user would then also have to specify an environment variable to their custom godot build, e.g. GODOT_BIN. The feature could then be detected in gdnative-bindings/build.rs and if it is enabled and the var set then the api.json can be re-built on the fly.

if cfg!(feature = "godot_custom_build") {
    let godot_bin = env::var("GODOT_BIN").expect("GODOT_BIN not set");

    // Call std::process and generate the api.json
}

I believe this would be a big enhancement to support the workflow of custom builds and would not be too disruptive. It would require adding a feature flag to the crates, adding the feature check to the build.rs and adding some minor logic to pick the correct api.json after it has been generated.

Seems like a good idea to me. Thanks for the suggestion! Could you create a PR for this?

[carmel4a]

Is the feature flag necessary? It may work that way: if some env var (let's say GODOT_BIN) is present and not empty - this behavior will occur, otherwise default api.json will be used. User will have even less to do to use custom Godot.
If nobody works on it, I may try to do this in +/- 2 weeks.

[bluenote10]

The user would then also have to specify an environment variable to their custom godot build, e.g. GODOT_BIN.

Could we also use which::which("godot") and fallback to $GODOT_BIN if it isn't set? I'd assume that Linux users typically symlink the binary into their path anyway.

[Bromeon]

@rminderhoud and @bluenote10: Thanks a lot for your input! I realized your ideas as a proof-of-concept in #833.

Let me know if you have time to test it or other feedback (you could leave it directly in the PR)! 🙂

@carmel4a: I think it's important that godot-rust in its default configuration behaves consistently. If the presence of an executable on the system alters runtime behavior (to the point of incompatibility) without the user opting in, that will lead to unpleasant surprises. That's why custom-godot is now a default-off feature flag.