Emit detailed message when failing on unknown targets

src/lib.rs

@@ -351,6 +351,8 @@ enum ErrorKind {
     ToolFamilyMacroNotFound,
     /// Invalid target.
     InvalidTarget,
+    /// Unknown target.
+    UnknownTarget,
     /// Invalid rustc flag.
     InvalidFlag,
     #[cfg(feature = "parallel")]

src/target.rs

@@ -59,8 +59,20 @@ impl FromStr for TargetInfo<'_> {
             Ok(info.clone())
         } else {
             Err(Error::new(
-                ErrorKind::InvalidTarget,
-                format!("unknown target `{target_triple}`"),
+                ErrorKind::UnknownTarget,
+                format!(
+                    "unknown target `{target_triple}`.
+
+NOTE: `cc-rs` only supports a fixed set of targets when not in a build script.
+- If adding a new target, you will need to fork of `cc-rs` until the target
+  has landed on nightly and the auto-generated list has been updated. See also
+  the `rustc` dev guide on adding a new target:
+  https://rustc-dev-guide.rust-lang.org/building/new-target.html
+- If using a custom target, prefer to upstream it to `rustc` if possible,
+  otherwise open an issue with `cc-rs`:
+  https://github.com/rust-lang/cc-rs/issues/new
+"
+                ),
             ))
         }
     }