README.md - platform/external/rust/crates/no-panic - Git at Google

 \#\[no\_panic\]
 ===============

 [<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)
 [<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)
 [<img alt="docs.rs" src="https://img.shields.io/badge/docs.rs-no--panic-66c2a5?style=for-the-badge&labelColor=555555&logoColor=white&logo=data:image/svg+xml;base64,PHN2ZyByb2xlPSJpbWciIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgdmlld0JveD0iMCAwIDUxMiA1MTIiPjxwYXRoIGZpbGw9IiNmNWY1ZjUiIGQ9Ik00ODguNiAyNTAuMkwzOTIgMjE0VjEwNS41YzAtMTUtOS4zLTI4LjQtMjMuNC0zMy43bC0xMDAtMzcuNWMtOC4xLTMuMS0xNy4xLTMuMS0yNS4zIDBsLTEwMCAzNy41Yy0xNC4xIDUuMy0yMy40IDE4LjctMjMuNCAzMy43VjIxNGwtOTYuNiAzNi4yQzkuMyAyNTUuNSAwIDI2OC45IDAgMjgzLjlWMzk0YzAgMTMuNiA3LjcgMjYuMSAxOS45IDMyLjJsMTAwIDUwYzEwLjEgNS4xIDIyLjEgNS4xIDMyLjIgMGwxMDMuOS01MiAxMDMuOSA1MmMxMC4xIDUuMSAyMi4xIDUuMSAzMi4yIDBsMTAwLTUwYzEyLjItNi4xIDE5LjktMTguNiAxOS45LTMyLjJWMjgzLjljMC0xNS05LjMtMjguNC0yMy40LTMzLjd6TTM1OCAyMTQuOGwtODUgMzEuOXYtNjguMmw4NS0zN3Y3My4zek0xNTQgMTA0LjFsMTAyLTM4LjIgMTAyIDM4LjJ2LjZsLTEwMiA0MS40LTEwMi00MS40di0uNnptODQgMjkxLjFsLTg1IDQyLjV2LTc5LjFsODUtMzguOHY3NS40em0wLTExMmwtMTAyIDQxLjQtMTAyLTQxLjR2LS42bDEwMi0zOC4yIDEwMiAzOC4ydi42em0yNDAgMTEybC04NSA0Mi41di03OS4xbDg1LTM4Ljh2NzUuNHptMC0xMTJsLTEwMiA0MS40LTEwMi00MS40di0uNmwxMDItMzguMiAxMDIgMzguMnYuNnoiPjwvcGF0aD48L3N2Zz4K" height="20">](https://docs.rs/no-panic)
 [<img alt="build status" src="https://img.shields.io/github/workflow/status/dtolnay/no-panic/CI/master?style=for-the-badge" height="20">](https://github.com/dtolnay/no-panic/actions?query=branch%3Amaster)

 A Rust attribute macro to require that the compiler prove a function can't ever
 panic.

 ```toml
 [dependencies]
 no-panic = "0.1"
 ```

 ```rust
 use no_panic::no_panic;

 #[no_panic]
 fn demo(s: &str) -> &str {
     &s[1..]
 }

 fn main() {
     println!("{}", demo("input string"));
 }
 ```

 If the function does panic (or the compiler fails to prove that the function
 cannot panic), the program fails to compile with a linker error that identifies
 the function name. Let's trigger that by passing a string that cannot be sliced
 at the first byte:

 ```rust
 fn main() {
     println!("{}", demo("\u{1f980}input string"));
 }
 ```

 ```console
    Compiling no-panic-demo v0.0.1
 error: linking with `cc` failed: exit code: 1
   |
   = note: /no-panic-demo/target/release/deps/no_panic_demo-7170785b672ae322.no_p
 anic_demo1-cba7f4b666ccdbcbbf02b7348e5df1b2.rs.rcgu.o: In function `_$LT$no_pani
 c_demo..demo..__NoPanic$u20$as$u20$core..ops..drop..Drop$GT$::drop::h72f8f423002
 b8d9f':
           no_panic_demo1-cba7f4b666ccdbcbbf02b7348e5df1b2.rs:(.text._ZN72_$LT$no
 _panic_demo..demo..__NoPanic$u20$as$u20$core..ops..drop..Drop$GT$4drop17h72f8f42
 3002b8d9fE+0x2): undefined reference to `

           ERROR[no-panic]: detected panic in function `demo`
           '
           collect2: error: ld returned 1 exit status
 ```

 The error is not stellar but notice the ERROR\[no-panic\] part at the end that
 provides the name of the offending function.

 *Compiler support: requires rustc 1.31+*

 <br>

 ### Caveats

 - Functions that require some amount of optimization to prove that they do not
   panic may no longer compile in debug mode after being marked `#[no_panic]`.

 - Panic detection happens at link time across the entire dependency graph, so
   any Cargo commands that do not invoke a linker will not trigger panic
   detection. This includes `cargo build` of library crates and `cargo check` of
   binary and library crates.

 - The attribute is useless in code built with `panic = "abort"`.

 If you find that code requires optimization to pass `#[no_panic]`, either make
 no-panic an optional dependency that you only enable in release builds, or add a
 section like the following to Cargo.toml to enable very basic optimization in
 debug builds.

 ```toml
 [profile.dev]
 opt-level = 1
 ```

 If the code that you need to prove isn't panicking makes function calls to
 non-generic non-inline functions from a different crate, you may need thin LTO
 enabled for the linker to deduce those do not panic.

 ```toml
 [profile.release]
 lto = "thin"
 ```

 If you want no\_panic to just assume that some function you call doesn't panic,
 and get Undefined Behavior if it does at runtime, see [dtolnay/no-panic#16]; try
 wrapping that call in an `unsafe extern "C"` wrapper.

 [dtolnay/no-panic#16]: https://github.com/dtolnay/no-panic/issues/16

 <br>

 ### Acknowledgments

 The linker error technique is based on [Kixunil]'s crate [`dont_panic`]. Check
 out that crate for other convenient ways to require absence of panics.

 [Kixunil]: https://github.com/Kixunil
 [`dont_panic`]: https://github.com/Kixunil/dont_panic

 <br>

 #### License

 <sup>
 Licensed under either of <a href="LICENSE-APACHE">Apache License, Version
 2.0</a> or <a href="LICENSE-MIT">MIT license</a> at your option.
 </sup>

 <br>

 <sub>
 Unless you explicitly state otherwise, any contribution intentionally submitted
 for inclusion in this crate by you, as defined in the Apache-2.0 license, shall
 be dual licensed as above, without any additional terms or conditions.
 </sub>
	\#\[no\_panic\]
	===============

	[<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)
	[<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)
	[<img alt="docs.rs" src="https://img.shields.io/badge/docs.rs-no--panic-66c2a5?style=for-the-badge&labelColor=555555&logoColor=white&logo=data:image/svg+xml;base64,PHN2ZyByb2xlPSJpbWciIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgdmlld0JveD0iMCAwIDUxMiA1MTIiPjxwYXRoIGZpbGw9IiNmNWY1ZjUiIGQ9Ik00ODguNiAyNTAuMkwzOTIgMjE0VjEwNS41YzAtMTUtOS4zLTI4LjQtMjMuNC0zMy43bC0xMDAtMzcuNWMtOC4xLTMuMS0xNy4xLTMuMS0yNS4zIDBsLTEwMCAzNy41Yy0xNC4xIDUuMy0yMy40IDE4LjctMjMuNCAzMy43VjIxNGwtOTYuNiAzNi4yQzkuMyAyNTUuNSAwIDI2OC45IDAgMjgzLjlWMzk0YzAgMTMuNiA3LjcgMjYuMSAxOS45IDMyLjJsMTAwIDUwYzEwLjEgNS4xIDIyLjEgNS4xIDMyLjIgMGwxMDMuOS01MiAxMDMuOSA1MmMxMC4xIDUuMSAyMi4xIDUuMSAzMi4yIDBsMTAwLTUwYzEyLjItNi4xIDE5LjktMTguNiAxOS45LTMyLjJWMjgzLjljMC0xNS05LjMtMjguNC0yMy40LTMzLjd6TTM1OCAyMTQuOGwtODUgMzEuOXYtNjguMmw4NS0zN3Y3My4zek0xNTQgMTA0LjFsMTAyLTM4LjIgMTAyIDM4LjJ2LjZsLTEwMiA0MS40LTEwMi00MS40di0uNnptODQgMjkxLjFsLTg1IDQyLjV2LTc5LjFsODUtMzguOHY3NS40em0wLTExMmwtMTAyIDQxLjQtMTAyLTQxLjR2LS42bDEwMi0zOC4yIDEwMiAzOC4ydi42em0yNDAgMTEybC04NSA0Mi41di03OS4xbDg1LTM4Ljh2NzUuNHptMC0xMTJsLTEwMiA0MS40LTEwMi00MS40di0uNmwxMDItMzguMiAxMDIgMzguMnYuNnoiPjwvcGF0aD48L3N2Zz4K" height="20">](https://docs.rs/no-panic)
	[<img alt="build status" src="https://img.shields.io/github/workflow/status/dtolnay/no-panic/CI/master?style=for-the-badge" height="20">](https://github.com/dtolnay/no-panic/actions?query=branch%3Amaster)

	A Rust attribute macro to require that the compiler prove a function can't ever
	panic.

	```toml
	[dependencies]
	no-panic = "0.1"
	```

	```rust
	use no_panic::no_panic;

	#[no_panic]
	fn demo(s: &str) -> &str {
	&s[1..]
	}

	fn main() {
	println!("{}", demo("input string"));
	}
	```

	If the function does panic (or the compiler fails to prove that the function
	cannot panic), the program fails to compile with a linker error that identifies
	the function name. Let's trigger that by passing a string that cannot be sliced
	at the first byte:

	```rust
	fn main() {
	println!("{}", demo("\u{1f980}input string"));
	}
	```

	```console
	Compiling no-panic-demo v0.0.1
	error: linking with `cc` failed: exit code: 1
	\|
	= note: /no-panic-demo/target/release/deps/no_panic_demo-7170785b672ae322.no_p
	anic_demo1-cba7f4b666ccdbcbbf02b7348e5df1b2.rs.rcgu.o: In function `_$LT$no_pani
	c_demo..demo..__NoPanic$u20$as$u20$core..ops..drop..Drop$GT$::drop::h72f8f423002
	b8d9f':
	no_panic_demo1-cba7f4b666ccdbcbbf02b7348e5df1b2.rs:(.text._ZN72_$LT$no
	_panic_demo..demo..__NoPanic$u20$as$u20$core..ops..drop..Drop$GT$4drop17h72f8f42
	3002b8d9fE+0x2): undefined reference to `

	ERROR[no-panic]: detected panic in function `demo`
	'
	collect2: error: ld returned 1 exit status
	```

	The error is not stellar but notice the ERROR\[no-panic\] part at the end that
	provides the name of the offending function.

	Compiler support: requires rustc 1.31+

	<br>

	### Caveats

	- Functions that require some amount of optimization to prove that they do not
	panic may no longer compile in debug mode after being marked `#[no_panic]`.

	- Panic detection happens at link time across the entire dependency graph, so
	any Cargo commands that do not invoke a linker will not trigger panic
	detection. This includes `cargo build` of library crates and `cargo check` of
	binary and library crates.

	- The attribute is useless in code built with `panic = "abort"`.

	If you find that code requires optimization to pass `#[no_panic]`, either make
	no-panic an optional dependency that you only enable in release builds, or add a
	section like the following to Cargo.toml to enable very basic optimization in
	debug builds.

	```toml
	[profile.dev]
	opt-level = 1
	```

	If the code that you need to prove isn't panicking makes function calls to
	non-generic non-inline functions from a different crate, you may need thin LTO
	enabled for the linker to deduce those do not panic.

	```toml
	[profile.release]
	lto = "thin"
	```

	If you want no\_panic to just assume that some function you call doesn't panic,
	and get Undefined Behavior if it does at runtime, see [dtolnay/no-panic#16]; try
	wrapping that call in an `unsafe extern "C"` wrapper.

	[dtolnay/no-panic#16]: https://github.com/dtolnay/no-panic/issues/16

	<br>

	### Acknowledgments

	The linker error technique is based on [Kixunil]'s crate [`dont_panic`]. Check
	out that crate for other convenient ways to require absence of panics.

	[Kixunil]: https://github.com/Kixunil
	[`dont_panic`]: https://github.com/Kixunil/dont_panic

	<br>

	#### License

	<sup>
	Licensed under either of <a href="LICENSE-APACHE">Apache License, Version
	2.0</a> or <a href="LICENSE-MIT">MIT license</a> at your option.
	</sup>

	<br>

	<sub>
	Unless you explicitly state otherwise, any contribution intentionally submitted
	for inclusion in this crate by you, as defined in the Apache-2.0 license, shall
	be dual licensed as above, without any additional terms or conditions.
	</sub>