Add 'custom-godot' feature: generate api.json during build step

Author: Bromeon

README.md

@@ -18,8 +18,8 @@ The bindings cover most of the exposed API of Godot 3.4, and are being used on a
 
 We are committed to keeping compatibility with the latest stable patch releases of all minor versions of the engine, starting from Godot 3.2:
 * Godot 3.4 (works out-of-the-box)
-* Godot 3.3 (needs api.json adjustment)
-* Godot 3.2 (needs api.json adjustment)
+* Godot 3.3 (needs feature `custom-godot`)
+* Godot 3.2 (needs feature `custom-godot`)
 
 For versions 3.2 and 3.3, some extra steps are needed, see _Custom builds_ below.
 
@@ -45,6 +45,7 @@ This means that `bindgen` was unable to find the C system headers for your platf
 
 ### Latest `master` version + Godot 3.4
 
+This is the recommended way of using godot-rust, if you want to benefit from latest features.
 After `bindgen` dependencies are installed, add the `gdnative` crate as a dependency, and set the crate type to `cdylib`:
 
 ```toml
@@ -57,7 +58,7 @@ crate-type = ["cdylib"]
 
 ### Godot 3.2.3-stable
 
-To access the last released version on crates.io, use the following. If you are starting, we recommend using the `master` version at this point, as there have been significant API changes since v0.9.3.
+To access the last released version on crates.io, use the following. Note that there have been significant API changes since v0.9.3 -- if you are starting to use godot-rust, we recommend using the `master` version instead.
 
 ```toml
 [dependencies]
@@ -69,9 +70,7 @@ crate-type = ["cdylib"]
 
 ### Custom builds
 
-To use the bindings with a non-default Godot version or a custom build, see [Using custom builds of Godot](https://godot-rust.github.io/book/advanced-guides/custom-godot.html) in the user guide.
-
-In short, you will need to generate `api.json` manually, using `godot --gdnative-generate-json-api api.json` to replace the file in the `gdnative-bindings` directory.
+To use the bindings with a different Godot version or a custom build of the engine, see [Custom Godot builds](https://godot-rust.github.io/book/advanced-guides/custom-godot.html) in the user guide.
 
 ### Async / `yield` support
 

gdnative-bindings/Cargo.toml

@@ -13,6 +13,7 @@ edition = "2018"
 [features]
 formatted = []
 one_class_one_file = []
+custom-godot = ["which"]
 
 [dependencies]
 gdnative-sys = { path = "../gdnative-sys", version = "0.9.3" }
@@ -23,3 +24,4 @@ bitflags = "1.3.2"
 [build-dependencies]
 heck = "0.4.0"
 gdnative_bindings_generator = { path = "../bindings_generator", version = "=0.9.3" }
+which = { optional = true, version = "4.2.2" }

gdnative-bindings/build.rs

@@ -7,6 +7,8 @@ use std::path::{Path, PathBuf};
 use std::process::Command;
 
 fn main() {
+    let just_generated_api = generate_api_if_needed();
+
     let api_data = std::fs::read_to_string("api.json").expect("Unable to read api.json");
 
     let out_path = PathBuf::from(env::var("OUT_DIR").unwrap());
@@ -39,8 +41,12 @@ fn main() {
     // Ignoring all but build.rs will keep from needless rebuilds.
     // Manually rebuilding the crate will ignore this.
     println!("cargo:rerun-if-changed=docs/");
-    println!("cargo:rerun-if-changed=api.json");
     println!("cargo:rerun-if-changed=build.rs");
+
+    // Avoid endless recompiling, if this script generates api.json
+    if !just_generated_api {
+        println!("cargo:rerun-if-changed=api.json");
+    }
 }
 
 /// Output all the class bindings into the `generated.rs` file.
@@ -147,3 +153,43 @@ fn format_file(output_rs: &Path) {
         }
     }
 }
+
+#[cfg(feature = "custom-godot")]
+fn generate_api_if_needed() -> bool {
+    let source: String;
+    let godot_bin: PathBuf;
+
+    if let Ok(string) = env::var("GODOT_BIN") {
+        source = format!("GODOT_BIN executable '{}'", string);
+        godot_bin = PathBuf::from(string);
+    } else if let Ok(path) = which::which("godot") {
+        source = "executable 'godot'".to_string();
+        godot_bin = path;
+    } else {
+        panic!(
+            "Feature 'custom-godot' requires an accessible 'godot' executable or \
+             a GODOT_BIN environment variable (with the path to the executable)."
+        );
+    };
+
+    // TODO call 'godot --version' and ensure >= 3.2 && < 4.0
+
+    let status = Command::new(godot_bin)
+        .arg("--gdnative-generate-json-api")
+        .arg("api.json")
+        .status()
+        .unwrap_or_else(|err| panic!("Failed to invoke {}; error {}", source, err));
+
+    assert!(
+        status.success(),
+        "Custom Godot command exited with status {}",
+        status.code().map_or("?".to_string(), |f| f.to_string())
+    );
+
+    true
+}
+
+#[cfg(not(feature = "custom-godot"))]
+fn generate_api_if_needed() -> bool {
+    false
+}

gdnative/Cargo.toml

@@ -12,14 +12,17 @@ readme = "../README.md"
 edition = "2018"
 
 [features]
+# Public
+async = ["gdnative-async", "bindings"]
+bindings = ["gdnative-bindings"]
+custom-godot = ["gdnative-bindings/custom-godot"]
 default = ["bindings"]
 formatted = ["gdnative-bindings/formatted", "gdnative-bindings/one_class_one_file"]
 serde = ["gdnative-core/serde"]
 
+# Internal
 gd_test = ["gdnative-core/gd_test"]
 type_tag_fallback = ["gdnative-core/type_tag_fallback"]
-bindings = ["gdnative-bindings"]
-async = ["gdnative-async", "bindings"]
 
 [dependencies]
 gdnative-derive = { path = "../gdnative-derive", version = "=0.9.3" }

gdnative/src/lib.rs

@@ -40,11 +40,16 @@
 //! on `Ref`.
 //!
 //! ## Feature flags
+//! Functionality  toggles:
+//! * `async` -- *disabled* by default. Enables asyn functionality, see [`tasks`] module for details.
+//! * `serde` -- *disabled* by default. Enable for `serde` support. See also
+//!   [`Variant`](core_types::Variant).
 //!
+//! Affecting bindings generation:
 //! * `bindings` -- *enabled* by default. Includes the crates.io version of the bindings in the
 //!   `api` module. Disable if you want to use a custom Godot version.
-//! * `serde` -- *disabled* by default. Enable for `serde` support. See also
-//!   [`Variant`](core_types::Variant).
+//! * `custom-godot` -- *disabled* by default. When active, looks for a `GODOT_BIN` environment
+//!   variable pointing to the Godot executable, or a `godot` executable in the path.
 //! * `formatted` -- *disabled* by default. Enable if the generated binding source code should
 //!   be human-readable.
 //!

test/Cargo.toml

@@ -11,6 +11,7 @@ crate-type = ["cdylib"]
 [features]
 default = []
 type_tag_fallback = ["gdnative/type_tag_fallback"]
+custom-godot = ["gdnative/custom-godot"]
 
 [dependencies]
 gdnative = { path = "../gdnative", features = ["gd_test", "serde", "async"] }