Deprecate wasmtime_internal_error::anyhow; prefer wasmtime_internal_error::format_err (#12252)

* Deprecate `wasmtime_internal_error::anyhow`; prefer `wasmtime_internal_error::format_err`

* use `format_err!` instead of `anyhow!` in OOM test

Author: fitzgen

crates/error/src/error.rs

@@ -260,14 +260,14 @@ impl BoxedDynError {
 /// ```
 ///
 /// If you do not want to early-return, just to create the `Error`, then the
-/// [`anyhow!`][crate::anyhow] macro is preferred:
+/// [`format_err!`][crate::format_err] macro is preferred:
 ///
 /// ```
 /// # use wasmtime_internal_error as wasmtime;
-/// use wasmtime::{anyhow, Error};
+/// use wasmtime::{format_err, Error};
 ///
 /// let x = 42;
-/// let my_error: Error = anyhow!("whoops! {x}");
+/// let my_error: Error = format_err!("whoops! {x}");
 /// ```
 ///
 /// If, however, you happen to require a constructor function instead of a
@@ -511,7 +511,7 @@ impl From<Error> for Box<dyn core::error::Error + 'static> {
     }
 }
 
-/// Convert a [`Error`] into an [`anyhow::Error`].
+/// Convert a [`wasmtime::Error`][crate::Error] into an [`anyhow::Error`].
 ///
 /// # Example
 ///
@@ -642,8 +642,11 @@ impl Error {
     /// # use wasmtime_internal_error as wasmtime;
     /// use std::error::Error;
     ///
-    /// let anyhow_error = anyhow::Error::msg("whoops");
-    /// let boxed_error: Box<dyn Error + Send + Sync + 'static> = anyhow_error.into_boxed_dyn_error();
+    /// // You happen to have a boxed error trait object.
+    /// let orig_error = std::fs::read("XXX: some file that doesn't exist").unwrap_err();
+    /// let boxed_error: Box<dyn Error + Send + Sync + 'static> = Box::new(orig_error) as _;
+    ///
+    /// // You can turn it into a `wasmtime::Error` via `from_boxed`.
     /// let wasmtime_error = wasmtime::Error::from_boxed(boxed_error);
     /// # }
     /// ```

crates/error/src/macros.rs

@@ -11,7 +11,8 @@ use core::fmt::{self, write};
 
 /// Construct an [`Error`](crate::Error) via string formatting or another error.
 ///
-/// Like `anyhow::anyhow!` but for [`wasmtime::Error`][crate::Error].
+/// Like `anyhow::format_err!` or `anyhow::anyhow!` but for
+/// [`wasmtime::Error`][crate::Error].
 ///
 /// # String Formatting
 ///
@@ -20,16 +21,16 @@ use core::fmt::{self, write};
 ///
 /// ```
 /// # use wasmtime_internal_error as wasmtime;
-/// use wasmtime::{anyhow, Error};
+/// use wasmtime::{format_err, Error};
 ///
 /// let x = 42;
-/// let error: Error = anyhow!("x is {x}");
+/// let error: Error = format_err!("x is {x}");
 /// assert_eq!(error.to_string(), "x is 42");
 ///
-/// let error: Error = anyhow!("x / 2 is {}", x / 2);
+/// let error: Error = format_err!("x / 2 is {}", x / 2);
 /// assert_eq!(error.to_string(), "x / 2 is 21");
 ///
-/// let error: Error = anyhow!("x + 1 is {y}", y = x + 1);
+/// let error: Error = format_err!("x + 1 is {y}", y = x + 1);
 /// assert_eq!(error.to_string(), "x + 1 is 43");
 /// ```
 ///
@@ -45,7 +46,7 @@ use core::fmt::{self, write};
 /// #![cfg(feature = "std")]
 /// # use wasmtime_internal_error as wasmtime;
 /// use std::fmt;
-/// use wasmtime::{anyhow, Error};
+/// use wasmtime::{format_err, Error};
 ///
 /// #[derive(Debug)]
 /// struct SomeOtherError(u32);
@@ -58,13 +59,13 @@ use core::fmt::{self, write};
 ///
 /// impl std::error::Error for SomeOtherError {}
 ///
-/// let error: Error = anyhow!(SomeOtherError(36));
+/// let error: Error = format_err!(SomeOtherError(36));
 /// assert!(error.is::<SomeOtherError>());
 /// assert_eq!(error.to_string(), "some other error (code 36)");
 /// # }
 /// ```
 #[macro_export]
-macro_rules! anyhow {
+macro_rules! format_err {
     // Format-style invocation without explicit format arguments.
     ( $message:literal $(,)? ) => {
         $crate::Error::from_format_args($crate::macros::format_args!($message))
@@ -84,22 +85,24 @@ macro_rules! anyhow {
     }};
 }
 
-/// Identical to the [`anyhow!`][crate::anyhow] macro.
+/// Identical to the [`format_err!`][crate::format_err] macro.
 ///
-/// Provided for compatibility.
+/// This is provided for API compatibility with the `anyhow` crate, but you
+/// should prefer using `format_err!` instead.
 #[macro_export]
-macro_rules! format_err {
+#[deprecated = "Use `format_err!(...)` instead"]
+macro_rules! anyhow {
     ( $( $args:tt )* ) => {
-        anyhow!( $( $args )* )
+        $crate::format_err!( $( $args )* )
     };
 }
 
 /// Early exit from the current function with an error.
 ///
-/// This helper is equivalent to `return Err(anyhow!(...))`.
+/// This helper is equivalent to `return Err(format_err!(...))`.
 ///
-/// See the docs for the [`anyhow!`][crate::anyhow] macro for details on the
-/// kinds of errors that can be constructed.
+/// See the docs for the [`format_err!`][crate::format_err] macro for details on
+/// the kinds of errors that can be constructed.
 ///
 /// Like `anyhow::bail!` but for [`wasmtime::Error`][crate::Error].
 ///
@@ -128,7 +131,7 @@ macro_rules! format_err {
 #[macro_export]
 macro_rules! bail {
     ( $($args:tt)* ) => {{
-        return $crate::macros::Err($crate::anyhow!( $( $args )* ));
+        return $crate::macros::Err($crate::format_err!( $( $args )* ));
     }};
 }
 
@@ -139,7 +142,7 @@ macro_rules! bail {
 ///
 /// ```ignore
 /// if !condition {
-///     return Err(anyhow!(...));
+///     return Err(format_err!(...));
 /// }
 /// ```
 ///
@@ -291,7 +294,7 @@ pub mod formatting {
     impl Error {
         /// Construct an `Error` from format arguments.
         ///
-        /// Only for use by the `anyhow!` macro.
+        /// Only for use by the `format_err!` macro.
         #[doc(hidden)]
         pub fn from_format_args(args: fmt::Arguments<'_>) -> Self {
             if let Some(s) = args.as_str() {

crates/error/tests/tests.rs

@@ -13,7 +13,7 @@ use core::{
 };
 #[cfg(feature = "std")]
 use std::backtrace::BacktraceStatus;
-use wasmtime_internal_error::{Context, Error, OutOfMemory, Result, anyhow, bail, ensure};
+use wasmtime_internal_error::{Context, Error, OutOfMemory, Result, bail, ensure, format_err};
 
 #[derive(Debug)]
 struct TestError(u32);
@@ -244,41 +244,41 @@ fn backtrace() {
 }
 
 #[test]
-fn anyhow_macro_string_literal() {
-    let error = anyhow!("literal");
+fn format_err_macro_string_literal() {
+    let error = format_err!("literal");
     assert_eq!(error.to_string(), "literal");
 }
 
 #[test]
-fn anyhow_macro_format_implicit_args() {
+fn format_err_macro_format_implicit_args() {
     let x = 42;
     let y = 36;
-    let error = anyhow!("implicit args {x} {y}");
+    let error = format_err!("implicit args {x} {y}");
     assert_eq!(error.to_string(), "implicit args 42 36");
 }
 
 #[test]
-fn anyhow_macro_format_explicit_args() {
+fn format_err_macro_format_explicit_args() {
     let a = 84;
     let b = 72;
-    let error = anyhow!("explicit args {x} {y}", x = a / 2, y = b / 2);
+    let error = format_err!("explicit args {x} {y}", x = a / 2, y = b / 2);
     assert_eq!(error.to_string(), "explicit args 42 36");
 }
 
 #[test]
-fn anyhow_macro_core_error() {
+fn format_err_macro_core_error() {
     let error = TestError(42);
-    let error = anyhow!(error);
+    let error = format_err!(error);
     assert!(error.is::<TestError>());
     assert_eq!(error.to_string(), "TestError(42)");
 }
 
 #[test]
-fn anyhow_macro_core_error_chain() {
+fn format_err_macro_core_error_chain() {
     let error = ChainError::new("ouch", None);
     let error = ChainError::new("yikes", Some(Box::new(error)));
     let error = ChainError::new("whoops", Some(Box::new(error)));
-    let error = anyhow!(error);
+    let error = format_err!(error);
 
     let mut chain = error.chain();
 
@@ -295,9 +295,9 @@ fn anyhow_macro_core_error_chain() {
 }
 
 #[test]
-fn anyhow_macro_msg() {
+fn format_err_macro_msg() {
     let error = 42;
-    let error = anyhow!(error);
+    let error = format_err!(error);
     assert_eq!(error.to_string(), "42");
 }
 

crates/fuzzing/tests/oom.rs

@@ -4,7 +4,7 @@ use std::{
     sync::atomic::{AtomicU32, Ordering::SeqCst},
 };
 use wasmtime::Config;
-use wasmtime_error::{Error, OutOfMemory, Result, anyhow};
+use wasmtime_error::{Error, OutOfMemory, Result, format_err};
 use wasmtime_fuzzing::oom::{OomTest, OomTestAllocator};
 
 #[global_allocator]
@@ -70,7 +70,7 @@ static X: AtomicU32 = AtomicU32::new(42);
 fn error_fmt() -> Result<()> {
     OomTest::new().test(|| {
         let x = X.load(SeqCst);
-        let error = anyhow!("ouch: {x}");
+        let error = format_err!("ouch: {x}");
         ok_if_not_oom(error)
     })
 }