From 35b843ef309fbb9d710f5b770072d4fb38725582 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Thu, 28 Mar 2019 15:22:59 -0700 Subject: [PATCH] Add some help and documentation for unstable flags. --- src/bin/cargo/cli.rs | 15 ++++++- src/bin/cargo/commands/build.rs | 18 ++++++--- src/cargo/core/features.rs | 54 ++++++++++++++++++++++++-- src/cargo/core/mod.rs | 2 +- src/cargo/util/command_prelude.rs | 13 ++++--- src/doc/man/cargo-build.adoc | 12 ++++-- src/doc/man/generated/cargo-build.html | 12 ++++-- src/doc/src/reference/unstable.md | 5 ++- src/etc/man/cargo-build.1 | 22 ++++++++--- tests/testsuite/cargo_features.rs | 9 ++++- 10 files changed, 128 insertions(+), 34 deletions(-) diff --git a/src/bin/cargo/cli.rs b/src/bin/cargo/cli.rs index af02bbbfae7..ae1961929eb 100644 --- a/src/bin/cargo/cli.rs +++ b/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 ' for more information on a specific command.\n", ) .subcommands(commands::builtin()) } - diff --git a/src/bin/cargo/commands/build.rs b/src/bin/cargo/commands/build.rs index 367ab2e91eb..ba83b7c1f02 100644 --- a/src/bin/cargo/commands/build.rs +++ b/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(()) } diff --git a/src/cargo/core/features.rs b/src/cargo/core/features.rs index 4daed85d7ef..b62dc50704b 100644 --- a/src/cargo/core/features.rs +++ b/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; } diff --git a/src/cargo/core/mod.rs b/src/cargo/core/mod.rs index f94291f74e9..27265541130 100644 --- a/src/cargo/core/mod.rs +++ b/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; diff --git a/src/cargo/util/command_prelude.rs b/src/cargo/util/command_prelude.rs index 3c3c7976f93..21be7e86f4b 100644 --- a/src/cargo/util/command_prelude.rs +++ b/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 { diff --git a/src/doc/man/cargo-build.adoc b/src/doc/man/cargo-build.adoc index 2fc660f8cc6..a7b20d7de64 100644 --- a/src/doc/man/cargo-build.adoc +++ b/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 diff --git a/src/doc/man/generated/cargo-build.html b/src/doc/man/generated/cargo-build.html index 8739f29314e..b2884170539 100644 --- a/src/doc/man/generated/cargo-build.html +++ b/src/doc/man/generated/cargo-build.html @@ -185,8 +185,10 @@

Output Options

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 +nightly channel +and requires the -Z unstable-options flag to enable. +See https://github.com/rust-lang/cargo/issues/6790 for more information.

@@ -253,8 +255,10 @@

Display Options

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 +nightly channel +and requires the -Z unstable-options flag to enable. +See https://github.com/rust-lang/cargo/issues/5579 for more information.

diff --git a/src/doc/src/reference/unstable.md b/src/doc/src/reference/unstable.md index a5b2950c317..e1546b832c0 100644 --- a/src/doc/src/reference/unstable.md +++ b/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 diff --git a/src/etc/man/cargo-build.1 b/src/etc/man/cargo-build.1 index bb81bd76e8a..20797f2378d 100644 --- a/src/etc/man/cargo-build.1 +++ b/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 diff --git a/tests/testsuite/cargo_features.rs b/tests/testsuite/cargo_features.rs index 3581a51b151..a0872c49caa 100644 --- a/tests/testsuite/cargo_features.rs +++ b/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")