Support for multiple Godot versions and pre-generated bindings in 0.10

ghost commented 4 years ago

With Godot 3.2 becoming stable, and breaking changes happening in the engine, we would like to be able to support multiple versions of Godot in the future. To accomplish this, each stable Godot release branch will get their own API crate, in the form of gdnative-bindings-{major}-{minor}, starting from Godot 3.2.

Additionally, the API crates will have a default pregenerated feature flag, which when enabled will make the crate use pre-generated code in order to save compilation time. Users may specify default-features = false to opt out of this and run generation on their own machines.

Godot 3.2 will be the first version we'll commit to supporting, meaning that it will be considered a breaking change to drop it, and a maintenance branch will be created if that happens. Support for the Godot 3.1.x branch may be dropped in future minor versions without further maintenance. The existing gdnative-bindings crate will have the Godot 3.2 API, and will be deprecated after it's last release as part of 0.10. It will stay as-is after the release.

Details

Versioning

The API crates will be versioned as follows:

Each API crate will share the compatibility of gdnative-core, i.e. same minor version in 0.x, and same major version after 1.0.
Godot patch version updates are not considered breaking changes, even if there should be a breaking change in Godot. This is to maintain point 1 when upstream version numbers differ in semantics from semver.

bindings_generator and gdnative-sys will be considered internal dependencies, and will always stay in 0.x. Their versions may go out of sync with gdnative-core, gdnative-derive, gdnative, and the API crates.

Implementation

Each API crate will have a gdnative-bindings-pregenerated-{major}-{minor}counterpart published on crates.io, which contains the pre-generated version, and is used as an optional dependency. When pregenerated is enabled, the API crate will simply re-export everything from the -pregenerated- crate. Otherwise, it will invoke bindings_generator to generate code as it works now.

API crates will be generated on packaging, and will not be checked into the source tree.

Steps

[ ] Implement the binary api-crate-generator which will handle generating and packaging API crates.
[ ] Create an internal in-tree API crate used for development, which will not be published. Migrate examples and tests to the internal crate .
[ ] Add documentation about the API crates.
[ ] (At 0.10 release) deprecate gdnative-bindings after a final update.

ghost commented 4 years ago

Delayed this to 0.9, as larger changes are planned, and we decided to release 0.8 as a small, relatively stable update before the big changes land.

ghost commented 4 years ago

Further delayed to 0.10, but it can be made non-breaking if we introduce engine version feature flags in 0.9.

chitoyuu commented 1 year ago

With building for custom versions being much more ergonomic than back when this issue was created, and new ideas proposed in #814 to handle backward compatibility, especially with #973 making ptrcalls opt-in, there might no longer be a need to distribute multiple versions of pre-generated bindings.

Closing for now.

godot-rust / gdnative