Add BINDGEN_OUTPUT_FILE export

Merges: #21

README.md

@@ -43,7 +43,7 @@ The `RIOT_CC` and `RIOT_CFLAGS` are made available to dependent crates through
 Cargo (as `DEP_RIOT_SYS_CC` etc); see [riot-wrappers]'s build.sh for an example. Similarly,
 custom markers are made available based on the presence of certain defines or features in RIOT
 as downstream crates require that information (typically to allow a crate to work across a
-wider range of RIOT versions); see the comments in `build.rs` for details.
+wider range of RIOT versions); see the section below for details.
 
 
 ### Extension
@@ -95,6 +95,16 @@ unit `T` of the `phydat_unit_t` in its enum, but converts it to the generic unsp
 on RIOT versions that don't have the T type yet -- at least for as long as it supports
 2022.01).
 
+**Deprecation note / successor**: As of 2023-02, no new markers will be added, because
+implementing this mechanism here has shown to be impracitcal: Changes need to go into riot-sys
+first before they can be use (and tested in) with riot-wrappers. Instead, `BINDGEN_OUTPUT_FILE`
+is exported (usable as `DEP_RIOT_SYS_BINDGEN_OUTPUT_FILE`), which points to the Rust file
+generated by bindgen. Downstream crates can inspect that file, possibly using the same
+string-based methods as riot-sys uses, but without any cross-crate dependencies.
+
+Crates accessing the `BINDGEN_OUTPUT_FILE` should exercise the same caution that is recommended
+above for the use of markers.
+
 ---
 
 The types and constants of RIOT are translated in two forms:

build.rs

@@ -220,8 +220,9 @@ fn main() {
         .expect("Unable to generate bindings");
 
     let out_path = PathBuf::from(env::var("OUT_DIR").unwrap());
+    let bindgen_outfilename = out_path.join("bindings.rs");
     bindings
-        .write_to_file(out_path.join("bindings.rs"))
+        .write_to_file(&bindgen_outfilename)
         .expect("Couldn't write bindings!");
     // Store for inspection for markers; see there
     let mut bindgen_output = Vec::<u8>::new();
@@ -655,6 +656,11 @@ fn main() {
     // let downstream crates know we're building for riot-rs
     #[cfg(feature = "riot-rs")]
     println!("cargo:MARKER_riot_rs=1");
+
+    println!(
+        "cargo:BINDGEN_OUTPUT_FILE={}",
+        bindgen_outfilename.display()
+    );
 }
 
 #[cfg(feature = "riot-rs")]

src/lib.rs

@@ -39,7 +39,7 @@
 //! Cargo (as `DEP_RIOT_SYS_CC` etc); see [riot-wrappers]'s build.sh for an example. Similarly,
 //! custom markers are made available based on the presence of certain defines or features in RIOT
 //! as downstream crates require that information (typically to allow a crate to work across a
-//! wider range of RIOT versions); see the comments in `build.rs` for details.
+//! wider range of RIOT versions); see the section below for details.
 //!
 //!
 //! ## Extension
@@ -91,6 +91,16 @@
 //! on RIOT versions that don't have the T type yet -- at least for as long as it supports
 //! 2022.01).
 //!
+//! **Deprecation note / successor**: As of 2023-02, no new markers will be added, because
+//! implementing this mechanism here has shown to be impracitcal: Changes need to go into riot-sys
+//! first before they can be use (and tested in) with riot-wrappers. Instead, `BINDGEN_OUTPUT_FILE`
+//! is exported (usable as `DEP_RIOT_SYS_BINDGEN_OUTPUT_FILE`), which points to the Rust file
+//! generated by bindgen. Downstream crates can inspect that file, possibly using the same
+//! string-based methods as riot-sys uses, but without any cross-crate dependencies.
+//!
+//! Crates accessing the `BINDGEN_OUTPUT_FILE` should exercise the same caution that is recommended
+//! above for the use of markers.
+//!
 //! ---
 //!
 //! The types and constants of RIOT are translated in two forms: