1\#\[no\_panic\] 2=============== 3 4[<img alt="github" src="https://img.shields.io/badge/github-dtolnay/no--panic-8da0cb?style=for-the-badge&labelColor=555555&logo=github" height="20">](https://github.com/dtolnay/no-panic) 5[<img alt="crates.io" src="https://img.shields.io/crates/v/no-panic.svg?style=for-the-badge&color=fc8d62&logo=rust" height="20">](https://crates.io/crates/no-panic) 6[<img alt="docs.rs" src="https://img.shields.io/badge/docs.rs-no--panic-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs" height="20">](https://docs.rs/no-panic) 7[<img alt="build status" src="https://img.shields.io/github/actions/workflow/status/dtolnay/no-panic/ci.yml?branch=master&style=for-the-badge" height="20">](https://github.com/dtolnay/no-panic/actions?query=branch%3Amaster) 8 9A Rust attribute macro to require that the compiler prove a function can't ever 10panic. 11 12```toml 13[dependencies] 14no-panic = "0.1" 15``` 16 17```rust 18use no_panic::no_panic; 19 20#[no_panic] 21fn demo(s: &str) -> &str { 22 &s[1..] 23} 24 25fn main() { 26 println!("{}", demo("input string")); 27} 28``` 29 30If the function does panic (or the compiler fails to prove that the function 31cannot panic), the program fails to compile with a linker error that identifies 32the function name. Let's trigger that by passing a string that cannot be sliced 33at the first byte: 34 35```rust 36fn main() { 37 println!("{}", demo("\u{1f980}input string")); 38} 39``` 40 41```console 42 Compiling no-panic-demo v0.0.1 43error: linking with `cc` failed: exit code: 1 44 | 45 = note: /no-panic-demo/target/release/deps/no_panic_demo-7170785b672ae322.no_p 46anic_demo1-cba7f4b666ccdbcbbf02b7348e5df1b2.rs.rcgu.o: In function `_$LT$no_pani 47c_demo..demo..__NoPanic$u20$as$u20$core..ops..drop..Drop$GT$::drop::h72f8f423002 48b8d9f': 49 no_panic_demo1-cba7f4b666ccdbcbbf02b7348e5df1b2.rs:(.text._ZN72_$LT$no 50_panic_demo..demo..__NoPanic$u20$as$u20$core..ops..drop..Drop$GT$4drop17h72f8f42 513002b8d9fE+0x2): undefined reference to ` 52 53 ERROR[no-panic]: detected panic in function `demo` 54 ' 55 collect2: error: ld returned 1 exit status 56``` 57 58The error is not stellar but notice the ERROR\[no-panic\] part at the end that 59provides the name of the offending function. 60 61<br> 62 63### Caveats 64 65- Functions that require some amount of optimization to prove that they do not 66 panic may no longer compile in debug mode after being marked `#[no_panic]`. 67 68- Panic detection happens at link time across the entire dependency graph, so 69 any Cargo commands that do not invoke a linker will not trigger panic 70 detection. This includes `cargo build` of library crates and `cargo check` of 71 binary and library crates. 72 73- The attribute is useless in code built with `panic = "abort"`. Code must be 74 built with `panic = "unwind"` (the default) in order for any panics to be 75 detected. After confirming absence of panics, you can of course still ship 76 your software as a `panic = "abort"` build. 77 78- Const functions are not supported. The attribute will fail to compile if 79 placed on a `const fn`. 80 81If you find that code requires optimization to pass `#[no_panic]`, either make 82no-panic an optional dependency that you only enable in release builds, or add a 83section like the following to your Cargo.toml or .cargo/config.toml to enable 84very basic optimization in debug builds. 85 86```toml 87[profile.dev] 88opt-level = 1 89``` 90 91If the code that you need to prove isn't panicking makes function calls to 92non-generic non-inline functions from a different crate, you may need thin LTO 93enabled for the linker to deduce those do not panic. 94 95```toml 96[profile.release] 97lto = "thin" 98``` 99 100If thin LTO isn't cutting it, the next thing to try would be fat LTO with a 101single codegen unit: 102 103```toml 104[profile.release] 105lto = "fat" 106codegen-units = 1 107``` 108 109If you want no\_panic to just assume that some function you call doesn't panic, 110and get Undefined Behavior if it does at runtime, see [dtolnay/no-panic#16]; try 111wrapping that call in an `unsafe extern "C"` wrapper. 112 113[dtolnay/no-panic#16]: https://github.com/dtolnay/no-panic/issues/16 114 115<br> 116 117### Acknowledgments 118 119The linker error technique is based on [Kixunil]'s crate [`dont_panic`]. Check 120out that crate for other convenient ways to require absence of panics. 121 122[Kixunil]: https://github.com/Kixunil 123[`dont_panic`]: https://github.com/Kixunil/dont_panic 124 125<br> 126 127#### License 128 129<sup> 130Licensed under either of <a href="LICENSE-APACHE">Apache License, Version 1312.0</a> or <a href="LICENSE-MIT">MIT license</a> at your option. 132</sup> 133 134<br> 135 136<sub> 137Unless you explicitly state otherwise, any contribution intentionally submitted 138for inclusion in this crate by you, as defined in the Apache-2.0 license, shall 139be dual licensed as above, without any additional terms or conditions. 140</sub> 141
