Add custom-fallback Backend

.github/workflows/tests.yml

@@ -358,3 +358,23 @@ jobs:
         run: cargo test --target wasm32-wasip1
       - name: WASI 0.2 Test
         run: cargo test --target wasm32-wasip2
+
+  fallback:
+    name: Custom Fallback
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: 1.82
+          targets: thumbv6m-none-eabi # A target getrandom doesn't currently support
+      - uses: Swatinem/rust-cache@v2
+      - name: No Fallback (Should Fail)
+        run: $(cargo build --target thumbv6m-none-eabi; if [ $? -ne 0 ]; then exit 0; else exit 1; fi)
+        working-directory: fallback_test
+      - name: Fallback
+        run: cargo build --target thumbv6m-none-eabi --features fallback
+        working-directory: fallback_test
+      - name: Double Fallback (Should Fail)
+        run: $(cargo build --target thumbv6m-none-eabi --features fallback,fail-double-definition; if [ $? -ne 0 ]; then exit 0; else exit 1; fi)
+        working-directory: fallback_test

.gitignore

@@ -2,3 +2,5 @@
 **/*.rs.bk
 nopanic_check/Cargo.lock
 nopanic_check/target/
+fallback_test/Cargo.lock
+fallback_test/target/

Cargo.toml

@@ -25,6 +25,12 @@ rustc-dep-of-std = ["dep:compiler_builtins", "dep:core"]
 # i.e. avoid unconditionally enabling it in library crates.
 wasm_js = ["dep:wasm-bindgen", "dep:js-sys"]
 
+# Optional backend: custom-fallback
+# This flag allows a custom fallback backend.
+# This will be used as a last-resort instead of raising a compiler error when
+# no other backend is available.
+custom-fallback = []
+
 [dependencies]
 cfg-if = "1"
 
@@ -90,6 +96,7 @@ check-cfg = [
   'cfg(getrandom_test_linux_without_fallback)',
   'cfg(getrandom_test_netbsd_fallback)',
   'cfg(target_os, values("cygwin"))', # TODO(MSRV 1.86): Remove this.
+  'cfg(getrandom_no_custom_fallback)',
 ]
 
 [package.metadata.docs.rs]

fallback_test/Cargo.toml

@@ -0,0 +1,19 @@
+[package]
+name = "fallback_test"
+description = "Test crate for assessing the custom-fallback feature"
+version = "0.1.0"
+edition = "2021"
+publish = false
+
+[dependencies]
+getrandom = { path = "..", default-features = false }
+
+[features]
+fallback = ["getrandom/custom-fallback"]
+fail-double-definition = ["fallback"]
+
+[profile.release]
+panic = "abort"
+
+[profile.dev]
+panic = "abort"

fallback_test/src/main.rs

@@ -0,0 +1,56 @@
+#![no_std]
+#![no_main]
+
+#[panic_handler]
+fn handle(_info: &core::panic::PanicInfo) -> ! {
+    loop {}
+}
+
+use getrandom::{Backend, Error};
+
+/// This implementation fills using a constant value of 4.
+///
+/// WARNING: this custom implementation is for testing purposes ONLY!
+struct ConstantBackend;
+
+unsafe impl Backend for ConstantBackend {
+    #[inline]
+    fn fill_uninit(dest: &mut [core::mem::MaybeUninit<u8>]) -> Result<(), Error> {
+        for out in dest {
+            // Chosen by fair dice roll
+            out.write(4);
+        }
+
+        Ok(())
+    }
+}
+
+#[cfg(feature = "fallback")]
+const _: () = {
+    getrandom::set_backend!(ConstantBackend);
+};
+
+// This second call will cause the following compile-time error:
+/*
+error: symbol `__getrandom_v03_fallback_fill_uninit` is already defined
+  --> src\main.rs:43:1
+   |
+43 | getrandom::set_backend!(ConstantBackend);
+   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+   |
+   = note: this error originates in the macro `getrandom::set_backend` (in Nightly builds, run with -Z macro-backtrace for more info)
+
+error: could not compile `fallback_test` (bin "fallback_test") due to 1 previous error
+*/
+#[cfg(feature = "fail-double-definition")]
+const _: () = {
+    getrandom::set_backend!(ConstantBackend);
+};
+
+#[no_mangle]
+pub extern "C" fn _start() {
+    let mut dest = [0u8; 13];
+    let result = getrandom::fill(&mut dest);
+    assert!(result.is_ok());
+    assert_eq!(dest, [4; 13]);
+}