Add some help and documentation for unstable flags.

src/bin/cargo/cli.rs

@@ -2,6 +2,7 @@ use clap;
 
 use clap::{AppSettings, Arg, ArgMatches};
 
+use cargo::core::features;
 use cargo::{self, CliResult, Config};
 
 use super::commands;
@@ -37,6 +38,19 @@ Available unstable (nightly-only) flags:
 
 Run with 'cargo -Z [FLAG] [SUBCOMMAND]'"
         );
+        if !features::nightly_features_allowed() {
+            println!(
+                "\nUnstable flags are only available on the nightly channel \
+                 of Cargo, but this is the `{}` channel.\n\
+                 {}",
+                features::channel(),
+                features::SEE_CHANNELS
+            );
+        }
+        println!(
+            "\nSee https://doc.rust-lang.org/nightly/cargo/reference/unstable.html \
+             for more information about these flags."
+        );
         return Ok(());
     }
 
@@ -236,4 +250,3 @@ See 'cargo help <command>' for more information on a specific command.\n",
         )
         .subcommands(commands::builtin())
 }
-

src/bin/cargo/commands/build.rs

@@ -30,7 +30,13 @@ pub fn cli() -> App {
         .arg_features()
         .arg_target_triple("Build for the target triple")
         .arg_target_dir()
-        .arg(opt("out-dir", "Copy final artifacts to this directory").value_name("PATH"))
+        .arg(
+            opt(
+                "out-dir",
+                "Copy final artifacts to this directory (unstable)",
+            )
+            .value_name("PATH"),
+        )
         .arg_manifest_path()
         .arg_message_format()
         .arg_build_plan()
@@ -52,11 +58,11 @@ pub fn exec(config: &mut Config, args: &ArgMatches<'_>) -> CliResult {
     let mut compile_opts = args.compile_options(config, CompileMode::Build, Some(&ws))?;
 
     compile_opts.export_dir = args.value_of_path("out-dir", config);
-    if compile_opts.export_dir.is_some() && !config.cli_unstable().unstable_options {
-        Err(failure::format_err!(
-            "`--out-dir` flag is unstable, pass `-Z unstable-options` to enable it"
-        ))?;
-    };
+    if compile_opts.export_dir.is_some() {
+        config
+            .cli_unstable()
+            .fail_if_stable_opt("--out-dir", 6790)?;
+    }
     ops::compile(&ws, &compile_opts)?;
     Ok(())
 }

src/cargo/core/features.rs

@@ -55,6 +55,10 @@ use serde::{Deserialize, Serialize};
 
 use crate::util::errors::CargoResult;
 
+pub const SEE_CHANNELS: &str =
+    "See https://doc.rust-lang.org/book/appendix-07-nightly-rust.html for more information \
+     about Rust release channels.";
+
 /// The edition of the compiler (RFC 2052)
 #[derive(Clone, Copy, Debug, Hash, PartialOrd, Ord, Eq, PartialEq, Serialize, Deserialize)]
 pub enum Edition {
@@ -235,9 +239,11 @@ impl Features {
             }
             Status::Unstable if !nightly_features_allowed() => failure::bail!(
                 "the cargo feature `{}` requires a nightly version of \
-                 Cargo, but this is the `{}` channel",
+                 Cargo, but this is the `{}` channel\n\
+                 {}",
                 feature,
-                channel()
+                channel(),
+                SEE_CHANNELS
             ),
             Status::Unstable => {}
         }
@@ -327,7 +333,13 @@ pub struct CliUnstable {
 impl CliUnstable {
     pub fn parse(&mut self, flags: &[String]) -> CargoResult<()> {
         if !flags.is_empty() && !nightly_features_allowed() {
-            failure::bail!("the `-Z` flag is only accepted on the nightly channel of Cargo")
+            failure::bail!(
+                "the `-Z` flag is only accepted on the nightly channel of Cargo, \
+                 but this is the `{}` channel\n\
+                 {}",
+                channel(),
+                SEE_CHANNELS
+            );
         }
         for flag in flags {
             self.add(flag)?;
@@ -365,9 +377,43 @@ impl CliUnstable {
 
         Ok(())
     }
+
+    /// Generates an error if `-Z unstable-options` was not used.
+    /// Intended to be used when a user passes a command-line flag that
+    /// requires `-Z unstable-options`.
+    pub fn fail_if_stable_opt(&self, flag: &str, issue: u32) -> CargoResult<()> {
+        if !self.unstable_options {
+            let see = format!(
+                "See https://github.com/rust-lang/cargo/issues/{} for more \
+                 information about the `{}` flag.",
+                issue, flag
+            );
+            if nightly_features_allowed() {
+                failure::bail!(
+                    "the `{}` flag is unstable, pass `-Z unstable-options` to enable it\n\
+                     {}",
+                    flag,
+                    see
+                );
+            } else {
+                failure::bail!(
+                    "the `{}` flag is unstable, and only available on the nightly channel \
+                     of Cargo, but this is the `{}` channel\n\
+                     {}\n\
+                     {}",
+                    flag,
+                    channel(),
+                    SEE_CHANNELS,
+                    see
+                );
+            }
+        }
+        Ok(())
+    }
 }
 
-fn channel() -> String {
+/// Returns the current release channel ("stable", "beta", "nightly", "dev").
+pub fn channel() -> String {
     if let Ok(override_channel) = env::var("__CARGO_TEST_CHANNEL_OVERRIDE_DO_NOT_USE_THIS") {
         return override_channel;
     }

src/cargo/core/mod.rs

@@ -17,7 +17,7 @@ pub use self::workspace::{Members, Workspace, WorkspaceConfig, WorkspaceRootConf
 
 pub mod compiler;
 pub mod dependency;
-mod features;
+pub mod features;
 mod interning;
 pub mod manifest;
 pub mod package;

src/cargo/util/command_prelude.rs

@@ -141,7 +141,10 @@ pub trait AppExt: Sized {
     }
 
     fn arg_build_plan(self) -> Self {
-        self._arg(opt("build-plan", "Output the build plan in JSON"))
+        self._arg(opt(
+            "build-plan",
+            "Output the build plan in JSON (unstable)",
+        ))
     }
 
     fn arg_new_opts(self) -> Self {
@@ -315,10 +318,10 @@ pub trait ArgMatchesExt {
         build_config.message_format = message_format;
         build_config.release = self._is_present("release");
         build_config.build_plan = self._is_present("build-plan");
-        if build_config.build_plan && !config.cli_unstable().unstable_options {
-            Err(failure::format_err!(
-                "`--build-plan` flag is unstable, pass `-Z unstable-options` to enable it"
-            ))?;
+        if build_config.build_plan {
+            config
+                .cli_unstable()
+                .fail_if_stable_opt("--build-plan", 5579)?;
         };
 
         let opts = CompileOptions {

src/doc/man/cargo-build.adoc

@@ -44,8 +44,10 @@ include::options-target-dir.adoc[]
 *--out-dir* _DIRECTORY_::
     Copy final artifacts to this directory.
 +
-This option is unstable and available only on the nightly channel and requires
-the `-Z unstable-options` flag to enable.
+This option is unstable and available only on the
+link:https://doc.rust-lang.org/book/appendix-07-nightly-rust.html[nightly channel]
+and requires the `-Z unstable-options` flag to enable.
+See https://github.com/rust-lang/cargo/issues/6790 for more information.
 
 === Display Options
 
@@ -57,8 +59,10 @@ include::options-message-format.adoc[]
     Outputs a series of JSON messages to stdout that indicate the commands to
     run the build.
 +
-This option is unstable and available only on the nightly channel and requires
-the `-Z unstable-options` flag to enable.
+This option is unstable and available only on the
+link:https://doc.rust-lang.org/book/appendix-07-nightly-rust.html[nightly channel]
+and requires the `-Z unstable-options` flag to enable.
+See https://github.com/rust-lang/cargo/issues/5579 for more information.
 
 === Manifest Options
 

src/doc/man/generated/cargo-build.html

@@ -185,8 +185,10 @@ to <code>target</code> in the root of the workspace.</p>
 <dd>
 <p>Copy final artifacts to this directory.</p>
 <div class="paragraph">
-<p>This option is unstable and available only on the nightly channel and requires
-the <code>-Z unstable-options</code> flag to enable.</p>
+<p>This option is unstable and available only on the
+<a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">nightly channel</a>
+and requires the <code>-Z unstable-options</code> flag to enable.
+See <a href="https://github.com/rust-lang/cargo/issues/6790" class="bare">https://github.com/rust-lang/cargo/issues/6790</a> for more information.</p>
 </div>
 </dd>
 </dl>
@@ -253,8 +255,10 @@ terminal.</p>
 <p>Outputs a series of JSON messages to stdout that indicate the commands to
 run the build.</p>
 <div class="paragraph">
-<p>This option is unstable and available only on the nightly channel and requires
-the <code>-Z unstable-options</code> flag to enable.</p>
+<p>This option is unstable and available only on the
+<a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">nightly channel</a>
+and requires the <code>-Z unstable-options</code> flag to enable.
+See <a href="https://github.com/rust-lang/cargo/issues/5579" class="bare">https://github.com/rust-lang/cargo/issues/5579</a> for more information.</p>
 </div>
 </dd>
 </dl>

src/doc/src/reference/unstable.md

@@ -77,6 +77,7 @@ minimum versions that you are actually using. That is, if Cargo.toml says
 
 ### out-dir
 * Original Issue: [#4875](https://github.com/rust-lang/cargo/issues/4875)
+* Tracking Issue: [#6790](https://github.com/rust-lang/cargo/issues/6790)
 
 This feature allows you to specify the directory where artifacts will be
 copied to after they are built. Typically artifacts are only written to the
@@ -148,7 +149,7 @@ cargo +nightly build -Z config-profile
 
 ### Namespaced features
 * Original issue: [#1286](https://github.com/rust-lang/cargo/issues/1286)
-* Tracking Issue: [rust-lang/cargo#5565](https://github.com/rust-lang/cargo/issues/5565)
+* Tracking Issue: [#5565](https://github.com/rust-lang/cargo/issues/5565)
 
 Currently, it is not possible to have a feature and a dependency with the same
 name in the manifest. If you set `namespaced-features` to `true`, the namespaces
@@ -175,7 +176,7 @@ include the dependency as a requirement, as `foo = ["crate:foo"]`.
 
 
 ### Build-plan
-* Tracking Issue: [rust-lang/cargo#5579](https://github.com/rust-lang/cargo/issues/5579)
+* Tracking Issue: [#5579](https://github.com/rust-lang/cargo/issues/5579)
 
 The `--build-plan` argument for the `build` command will output JSON with
 information about which commands would be run without actually executing

src/etc/man/cargo-build.1

@@ -2,12 +2,12 @@
 .\"     Title: cargo-build
 .\"    Author: [see the "AUTHOR(S)" section]
 .\" Generator: Asciidoctor 1.5.8
-.\"      Date: 2018-12-20
+.\"      Date: 2019-03-28
 .\"    Manual: \ \&
 .\"    Source: \ \&
 .\"  Language: English
 .\"
-.TH "CARGO\-BUILD" "1" "2018-12-20" "\ \&" "\ \&"
+.TH "CARGO\-BUILD" "1" "2019-03-28" "\ \&" "\ \&"
 .ie \n(.g .ds Aq \(aq
 .el       .ds Aq '
 .ss \n[.ss] 0
@@ -189,8 +189,13 @@ to \fBtarget\fP in the root of the workspace.
 .RS 4
 Copy final artifacts to this directory.
 .sp
-This option is unstable and available only on the nightly channel and requires
-the \fB\-Z unstable\-options\fP flag to enable.
+This option is unstable and available only on the
+\c
+.URL "https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html" "nightly channel"
+and requires the \fB\-Z unstable\-options\fP flag to enable.
+See \c
+.URL "https://github.com/rust\-lang/cargo/issues/6790" "" " "
+for more information.
 .RE
 .SS "Display Options"
 .sp
@@ -292,8 +297,13 @@ The output format for diagnostic messages. Valid values:
 Outputs a series of JSON messages to stdout that indicate the commands to
 run the build.
 .sp
-This option is unstable and available only on the nightly channel and requires
-the \fB\-Z unstable\-options\fP flag to enable.
+This option is unstable and available only on the
+\c
+.URL "https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html" "nightly channel"
+and requires the \fB\-Z unstable\-options\fP flag to enable.
+See \c
+.URL "https://github.com/rust\-lang/cargo/issues/5579" "" " "
+for more information.
 .RE
 .SS "Manifest Options"
 .sp

tests/testsuite/cargo_features.rs

@@ -146,6 +146,7 @@ error: failed to parse manifest at `[..]`
 Caused by:
   the cargo feature `test-dummy-unstable` requires a nightly version of Cargo, \
   but this is the `stable` channel
+See [..]
 ",
         )
         .run();
@@ -207,6 +208,7 @@ Caused by:
 Caused by:
   the cargo feature `test-dummy-unstable` requires a nightly version of Cargo, \
   but this is the `stable` channel
+See [..]
 ",
         )
         .run();
@@ -248,6 +250,7 @@ error: failed to parse manifest at `[..]`
 Caused by:
   the cargo feature `test-dummy-unstable` requires a nightly version of Cargo, \
   but this is the `stable` channel
+See [..]
 ",
         )
         .run();
@@ -272,7 +275,11 @@ fn z_flags_rejected() {
         .build();
     p.cargo("build -Zprint-im-a-teapot")
         .with_status(101)
-        .with_stderr("error: the `-Z` flag is only accepted on the nightly channel of Cargo")
+        .with_stderr(
+            "error: the `-Z` flag is only accepted on the nightly \
+             channel of Cargo, but this is the `stable` channel\n\
+             See [..]",
+        )
         .run();
 
     p.cargo("build -Zarg")