mirror of
https://github.com/rust-lang/cargo
synced 2024-08-25 10:35:53 +00:00
Add some help and documentation for unstable flags.
This commit is contained in:
parent
63231f438a
commit
35b843ef30
|
@ -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())
|
||||
}
|
||||
|
||||
|
|
|
@ -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(())
|
||||
}
|
||||
|
|
|
@ -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;
|
||||
}
|
||||
|
|
|
@ -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;
|
||||
|
|
|
@ -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 {
|
||||
|
|
|
@ -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
|
||||
|
||||
|
|
|
@ -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>
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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")
|
||||
|
|
Loading…
Reference in a new issue