From 4b309bc47a78c18acad3daaae4084b2374b1aabf Mon Sep 17 00:00:00 2001 From: valadaptive Date: Fri, 7 Jun 2024 03:01:26 -0400 Subject: [PATCH] Rename out-dir to artifact-dir Per discussion in https://github.com/rust-lang/cargo/issues/6790. The --out-dir CLI option and out-dir config option are often confused with the OUT_DIR environment variable, when the two serve very different purposes (the former tells Cargo where to copy build artifacts to, whereas the OUT_DIR environment variable is set *by* Cargo to tell build scripts where to place their generated intermediate artifacts). Renaming the option to something less confusing is a prerequisite to stabilizing it. --- src/bin/cargo/commands/build.rs | 31 +++++++--- src/cargo/core/compiler/build_config.rs | 10 ++-- .../build_runner/compilation_files.rs | 4 +- src/cargo/core/compiler/build_runner/mod.rs | 2 +- src/cargo/util/command_prelude.rs | 18 ++++-- src/cargo/util/context/mod.rs | 2 + src/doc/man/cargo-build.md | 2 +- src/doc/man/generated_txt/cargo-build.txt | 2 +- src/doc/src/commands/cargo-build.md | 2 +- src/doc/src/reference/unstable.md | 26 ++++----- src/etc/man/cargo-build.1 | 2 +- .../testsuite/{out_dir.rs => artifact_dir.rs} | 56 +++++++++---------- .../cargo_build/help/stdout.term.svg | 2 +- tests/testsuite/collisions.rs | 10 ++-- tests/testsuite/main.rs | 2 +- 15 files changed, 100 insertions(+), 71 deletions(-) rename tests/testsuite/{out_dir.rs => artifact_dir.rs} (83%) diff --git a/src/bin/cargo/commands/build.rs b/src/bin/cargo/commands/build.rs index 308ce2ce6a7..26f7af31609 100644 --- a/src/bin/cargo/commands/build.rs +++ b/src/bin/cargo/commands/build.rs @@ -34,7 +34,7 @@ pub fn cli() -> Command { .arg_parallel() .arg_target_triple("Build for the target triple") .arg_target_dir() - .arg_out_dir() + .arg_artifact_dir() .arg_build_plan() .arg_unit_graph() .arg_timings() @@ -50,15 +50,32 @@ pub fn exec(gctx: &mut GlobalContext, args: &ArgMatches) -> CliResult { let mut compile_opts = args.compile_options(gctx, CompileMode::Build, Some(&ws), ProfileChecking::Custom)?; - if let Some(out_dir) = args.value_of_path("out-dir", gctx) { - compile_opts.build_config.export_dir = Some(out_dir); - } else if let Some(out_dir) = gctx.build_config()?.out_dir.as_ref() { - let out_dir = out_dir.resolve_path(gctx); - compile_opts.build_config.export_dir = Some(out_dir); + if let Some(artifact_dir) = args.value_of_path("artifact-dir", gctx) { + // If the user specifies `--artifact-dir`, use that + compile_opts.build_config.export_dir = Some(artifact_dir); + } else if let Some(artifact_dir) = args.value_of_path("out-dir", gctx) { + // `--out-dir` is deprecated, but still supported for now + gctx.shell() + .warn("the --out-dir flag has been changed to --artifact-dir")?; + compile_opts.build_config.export_dir = Some(artifact_dir); + } else if let Some(artifact_dir) = gctx.build_config()?.artifact_dir.as_ref() { + // If a CLI option is not specified for choosing the artifact dir, use the `artifact-dir` from the build config, if + // present + let artifact_dir = artifact_dir.resolve_path(gctx); + compile_opts.build_config.export_dir = Some(artifact_dir); + } else if let Some(artifact_dir) = gctx.build_config()?.out_dir.as_ref() { + // As a last priority, check `out-dir` in the build config + gctx.shell() + .warn("the out-dir config option has been changed to artifact-dir")?; + let artifact_dir = artifact_dir.resolve_path(gctx); + compile_opts.build_config.export_dir = Some(artifact_dir); } + if compile_opts.build_config.export_dir.is_some() { - gctx.cli_unstable().fail_if_stable_opt("--out-dir", 6790)?; + gctx.cli_unstable() + .fail_if_stable_opt("--artifact-dir", 6790)?; } + ops::compile(&ws, &compile_opts)?; Ok(()) } diff --git a/src/cargo/core/compiler/build_config.rs b/src/cargo/core/compiler/build_config.rs index 9536e58be56..0f66d6dbbc6 100644 --- a/src/cargo/core/compiler/build_config.rs +++ b/src/cargo/core/compiler/build_config.rs @@ -36,11 +36,11 @@ pub struct BuildConfig { /// A thread used by `cargo fix` to receive messages on a socket regarding /// the success/failure of applying fixes. pub rustfix_diagnostic_server: Rc>>, - /// The directory to copy final artifacts to. Note that even if `out_dir` is - /// set, a copy of artifacts still could be found a `target/(debug\release)` - /// as usual. - // Note that, although the cmd-line flag name is `out-dir`, in code we use - // `export_dir`, to avoid confusion with out dir at `target/debug/deps`. + /// The directory to copy final artifacts to. Note that even if + /// `artifact-dir` is set, a copy of artifacts still can be found at + /// `target/(debug\release)` as usual. + /// Named `export_dir` to avoid confusion with + /// `CompilationFiles::artifact_dir`. pub export_dir: Option, /// `true` to output a future incompatibility report at the end of the build pub future_incompat_report: bool, diff --git a/src/cargo/core/compiler/build_runner/compilation_files.rs b/src/cargo/core/compiler/build_runner/compilation_files.rs index 27c555a2694..41ef89d6f0b 100644 --- a/src/cargo/core/compiler/build_runner/compilation_files.rs +++ b/src/cargo/core/compiler/build_runner/compilation_files.rs @@ -121,7 +121,7 @@ pub struct OutputFile { /// If it should be linked into `target`, and what it should be called /// (e.g., without metadata). pub hardlink: Option, - /// If `--out-dir` is specified, the absolute path to the exported file. + /// If `--artifact-dir` is specified, the absolute path to the exported file. pub export_path: Option, /// Type of the file (library / debug symbol / else). pub flavor: FileFlavor, @@ -213,7 +213,7 @@ impl<'a, 'gctx: 'a> CompilationFiles<'a, 'gctx> { } } - /// Additional export directory from `--out-dir`. + /// Additional export directory from `--artifact-dir`. pub fn export_dir(&self) -> Option { self.export_dir.clone() } diff --git a/src/cargo/core/compiler/build_runner/mod.rs b/src/cargo/core/compiler/build_runner/mod.rs index c5a926d50af..ed4d6fcdc35 100644 --- a/src/cargo/core/compiler/build_runner/mod.rs +++ b/src/cargo/core/compiler/build_runner/mod.rs @@ -574,7 +574,7 @@ impl<'a, 'gctx> BuildRunner<'a, 'gctx> { if let Some(ref export_path) = output.export_path { if let Some(other_unit) = output_collisions.insert(export_path.clone(), unit) { self.bcx.gctx.shell().warn(format!( - "`--out-dir` filename collision.\n\ + "`--artifact-dir` filename collision.\n\ {}\ The exported filenames should be unique.\n\ {}", diff --git a/src/cargo/util/command_prelude.rs b/src/cargo/util/command_prelude.rs index 63435b50eaa..94e90fb66ff 100644 --- a/src/cargo/util/command_prelude.rs +++ b/src/cargo/util/command_prelude.rs @@ -393,25 +393,35 @@ pub trait CommandExt: Sized { ) } - fn arg_out_dir(self) -> Self { + fn arg_artifact_dir(self) -> Self { let unsupported_short_arg = { - let value_parser = UnknownArgumentValueParser::suggest_arg("--out-dir"); - Arg::new("unsupported-short-out-dir-flag") + let value_parser = UnknownArgumentValueParser::suggest_arg("--artifact-dir"); + Arg::new("unsupported-short-artifact-dir-flag") .help("") .short('O') .value_parser(value_parser) .action(ArgAction::SetTrue) .hide(true) }; + self._arg( opt( - "out-dir", + "artifact-dir", "Copy final artifacts to this directory (unstable)", ) .value_name("PATH") .help_heading(heading::COMPILATION_OPTIONS), ) ._arg(unsupported_short_arg) + ._arg( + opt( + "out-dir", + "Copy final artifacts to this directory (deprecated; use --artifact-dir instead)", + ) + .value_name("PATH") + .conflicts_with("artifact-dir") + .hide(true), + ) } } diff --git a/src/cargo/util/context/mod.rs b/src/cargo/util/context/mod.rs index 85eeccab6dc..b84c04ca58c 100644 --- a/src/cargo/util/context/mod.rs +++ b/src/cargo/util/context/mod.rs @@ -2609,7 +2609,9 @@ pub struct CargoBuildConfig { pub rustc_workspace_wrapper: Option, pub rustc: Option, pub rustdoc: Option, + // deprecated alias for artifact-dir pub out_dir: Option, + pub artifact_dir: Option, } /// Configuration for `build.target`. diff --git a/src/doc/man/cargo-build.md b/src/doc/man/cargo-build.md index 7eb8c7938dc..7c704314ca4 100644 --- a/src/doc/man/cargo-build.md +++ b/src/doc/man/cargo-build.md @@ -50,7 +50,7 @@ they have `required-features` that are missing. {{#options}} {{> options-target-dir }} -{{#option "`--out-dir` _directory_" }} +{{#option "`--artifact-dir` _directory_" }} Copy final artifacts to this directory. This option is unstable and available only on the diff --git a/src/doc/man/generated_txt/cargo-build.txt b/src/doc/man/generated_txt/cargo-build.txt index 1b9a5cae00b..316c068d0b5 100644 --- a/src/doc/man/generated_txt/cargo-build.txt +++ b/src/doc/man/generated_txt/cargo-build.txt @@ -188,7 +188,7 @@ OPTIONS . Defaults to target in the root of the workspace. - --out-dir directory + --artifact-dir directory Copy final artifacts to this directory. This option is unstable and available only on the nightly channel diff --git a/src/doc/src/commands/cargo-build.md b/src/doc/src/commands/cargo-build.md index 7156829c406..d0be79bbd0f 100644 --- a/src/doc/src/commands/cargo-build.md +++ b/src/doc/src/commands/cargo-build.md @@ -222,7 +222,7 @@ specified with the CARGO_TARGET_DIR environment variable, or the Defaults to target in the root of the workspace. -
--out-dir directory
+
--artifact-dir directory
Copy final artifacts to this directory.

This option is unstable and available only on the nightly channel diff --git a/src/doc/src/reference/unstable.md b/src/doc/src/reference/unstable.md index fce26e146c5..5e871aca5ae 100644 --- a/src/doc/src/reference/unstable.md +++ b/src/doc/src/reference/unstable.md @@ -28,9 +28,9 @@ how the feature works: * New command-line flags, options, and subcommands require the `-Z unstable-options` CLI option to also be included. For example, the new - `--out-dir` option is only available on nightly: + `--artifact-dir` option is only available on nightly: - ```cargo +nightly build --out-dir=out -Z unstable-options``` + ```cargo +nightly build --artifact-dir=out -Z unstable-options``` * `-Z` command-line flags are used to enable new functionality that may not have an interface, or the interface has not yet been designed, or for more @@ -74,7 +74,7 @@ For the latest nightly, see the [nightly version] of this page. * [msrv-policy](#msrv-policy) --- MSRV-aware resolver and version selection * [precise-pre-release](#precise-pre-release) --- Allows pre-release versions to be selected with `update --precise` * Output behavior - * [out-dir](#out-dir) --- Adds a directory where artifacts are copied to. + * [artifact-dir](#artifact-dir) --- Adds a directory where artifacts are copied to. * [Different binary name](#different-binary-name) --- Assign a name to the built binary that is separate from the crate name. * Compile behavior * [mtime-on-use](#mtime-on-use) --- Updates the last-modified timestamp on every dependency every time it is used, to provide a mechanism to delete unused artifacts. @@ -206,27 +206,27 @@ minimum versions that you are actually using. That is, if Cargo.toml says Indirect dependencies are resolved as normal so as not to be blocked on their minimal version validation. -## out-dir +## artifact-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 -`target/release` or `target/debug` directories. However, determining the -exact filename can be tricky since you need to parse JSON output. The -`--out-dir` flag makes it easier to predictably access the artifacts. Note -that the artifacts are copied, so the originals are still in the `target` -directory. Example: +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 +`target/release` or `target/debug` directories. However, determining the exact +filename can be tricky since you need to parse JSON output. The `--artifact-dir` +flag makes it easier to predictably access the artifacts. Note that the +artifacts are copied, so the originals are still in the `target` directory. +Example: ```sh -cargo +nightly build --out-dir=out -Z unstable-options +cargo +nightly build --artifact-dir=out -Z unstable-options ``` This can also be specified in `.cargo/config.toml` files. ```toml [build] -out-dir = "out" +artifact-dir = "out" ``` ## doctest-xcompile diff --git a/src/etc/man/cargo-build.1 b/src/etc/man/cargo-build.1 index 9b7a08e4ed1..23e49a15e16 100644 --- a/src/etc/man/cargo-build.1 +++ b/src/etc/man/cargo-build.1 @@ -222,7 +222,7 @@ specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the Defaults to \fBtarget\fR in the root of the workspace. .RE .sp -\fB\-\-out\-dir\fR \fIdirectory\fR +\fB\-\-artifact\-dir\fR \fIdirectory\fR .RS 4 Copy final artifacts to this directory. .sp diff --git a/tests/testsuite/out_dir.rs b/tests/testsuite/artifact_dir.rs similarity index 83% rename from tests/testsuite/out_dir.rs rename to tests/testsuite/artifact_dir.rs index 1b3d4a64ad1..47ef7bfc34e 100644 --- a/tests/testsuite/out_dir.rs +++ b/tests/testsuite/artifact_dir.rs @@ -1,4 +1,4 @@ -//! Tests for --out-dir flag. +//! Tests for --artifact-dir flag. use cargo_test_support::sleep_ms; use cargo_test_support::{basic_manifest, project}; @@ -12,8 +12,8 @@ fn binary_with_debug() { .file("src/main.rs", r#"fn main() { println!("Hello, World!") }"#) .build(); - p.cargo("build -Z unstable-options --out-dir out") - .masquerade_as_nightly_cargo(&["out-dir"]) + p.cargo("build -Z unstable-options --artifact-dir out") + .masquerade_as_nightly_cargo(&["artifact-dir"]) .enable_mac_dsym() .run(); check_dir_contents( @@ -49,8 +49,8 @@ fn static_library_with_debug() { ) .build(); - p.cargo("build -Z unstable-options --out-dir out") - .masquerade_as_nightly_cargo(&["out-dir"]) + p.cargo("build -Z unstable-options --artifact-dir out") + .masquerade_as_nightly_cargo(&["artifact-dir"]) .run(); check_dir_contents( &p.root().join("out"), @@ -85,8 +85,8 @@ fn dynamic_library_with_debug() { ) .build(); - p.cargo("build -Z unstable-options --out-dir out") - .masquerade_as_nightly_cargo(&["out-dir"]) + p.cargo("build -Z unstable-options --artifact-dir out") + .masquerade_as_nightly_cargo(&["artifact-dir"]) .enable_mac_dsym() .run(); check_dir_contents( @@ -121,8 +121,8 @@ fn rlib_with_debug() { ) .build(); - p.cargo("build -Z unstable-options --out-dir out") - .masquerade_as_nightly_cargo(&["out-dir"]) + p.cargo("build -Z unstable-options --artifact-dir out") + .masquerade_as_nightly_cargo(&["artifact-dir"]) .run(); check_dir_contents( &p.root().join("out"), @@ -165,8 +165,8 @@ fn include_only_the_binary_from_the_current_package() { .file("utils/src/lib.rs", "") .build(); - p.cargo("build -Z unstable-options --bin foo --out-dir out") - .masquerade_as_nightly_cargo(&["out-dir"]) + p.cargo("build -Z unstable-options --bin foo --artifact-dir out") + .masquerade_as_nightly_cargo(&["artifact-dir"]) .enable_mac_dsym() .run(); check_dir_contents( @@ -179,14 +179,14 @@ fn include_only_the_binary_from_the_current_package() { } #[cargo_test] -fn out_dir_is_a_file() { +fn artifact_dir_is_a_file() { let p = project() .file("src/main.rs", r#"fn main() { println!("Hello, World!") }"#) .file("out", "") .build(); - p.cargo("build -Z unstable-options --out-dir out") - .masquerade_as_nightly_cargo(&["out-dir"]) + p.cargo("build -Z unstable-options --artifact-dir out") + .masquerade_as_nightly_cargo(&["artifact-dir"]) .with_status(101) .with_stderr_contains("[ERROR] failed to create directory [..]") .run(); @@ -198,8 +198,8 @@ fn replaces_artifacts() { .file("src/main.rs", r#"fn main() { println!("foo") }"#) .build(); - p.cargo("build -Z unstable-options --out-dir out") - .masquerade_as_nightly_cargo(&["out-dir"]) + p.cargo("build -Z unstable-options --artifact-dir out") + .masquerade_as_nightly_cargo(&["artifact-dir"]) .run(); p.process( &p.root() @@ -211,8 +211,8 @@ fn replaces_artifacts() { sleep_ms(1000); p.change_file("src/main.rs", r#"fn main() { println!("bar") }"#); - p.cargo("build -Z unstable-options --out-dir out") - .masquerade_as_nightly_cargo(&["out-dir"]) + p.cargo("build -Z unstable-options --artifact-dir out") + .masquerade_as_nightly_cargo(&["artifact-dir"]) .run(); p.process( &p.root() @@ -240,8 +240,8 @@ fn avoid_build_scripts() { .file("b/build.rs", r#"fn main() { println!("hello-build-b"); }"#) .build(); - p.cargo("build -Z unstable-options --out-dir out -vv") - .masquerade_as_nightly_cargo(&["out-dir"]) + p.cargo("build -Z unstable-options --artifact-dir out -vv") + .masquerade_as_nightly_cargo(&["artifact-dir"]) .enable_mac_dsym() .with_stdout_contains("[a 0.0.1] hello-build-a") .with_stdout_contains("[b 0.0.1] hello-build-b") @@ -256,20 +256,20 @@ fn avoid_build_scripts() { } #[cargo_test] -fn cargo_build_out_dir() { +fn cargo_build_artifact_dir() { let p = project() .file("src/main.rs", r#"fn main() { println!("Hello, World!") }"#) .file( ".cargo/config.toml", r#" [build] - out-dir = "out" + artifact-dir = "out" "#, ) .build(); p.cargo("build -Z unstable-options") - .masquerade_as_nightly_cargo(&["out-dir"]) + .masquerade_as_nightly_cargo(&["artifact-dir"]) .enable_mac_dsym() .run(); check_dir_contents( @@ -282,18 +282,18 @@ fn cargo_build_out_dir() { } #[cargo_test] -fn unsupported_short_out_dir_flag() { +fn unsupported_short_artifact_dir_flag() { let p = project() .file("src/main.rs", r#"fn main() { println!("Hello, World!") }"#) .build(); p.cargo("build -Z unstable-options -O") - .masquerade_as_nightly_cargo(&["out-dir"]) + .masquerade_as_nightly_cargo(&["artifact-dir"]) .with_stderr( "\ error: unexpected argument '-O' found - tip: a similar argument exists: '--out-dir' + tip: a similar argument exists: '--artifact-dir' Usage: cargo[EXE] build [OPTIONS] @@ -305,7 +305,7 @@ For more information, try '--help'. } fn check_dir_contents( - out_dir: &Path, + artifact_dir: &Path, expected_linux: &[&str], expected_mac: &[&str], expected_win_msvc: &[&str], @@ -323,7 +323,7 @@ fn check_dir_contents( expected_linux }; - let actual = list_dir(out_dir); + let actual = list_dir(artifact_dir); let mut expected = expected.iter().map(|s| s.to_string()).collect::>(); expected.sort_unstable(); assert_eq!(actual, expected); diff --git a/tests/testsuite/cargo_build/help/stdout.term.svg b/tests/testsuite/cargo_build/help/stdout.term.svg index 6b297f59393..e426262f9c5 100644 --- a/tests/testsuite/cargo_build/help/stdout.term.svg +++ b/tests/testsuite/cargo_build/help/stdout.term.svg @@ -109,7 +109,7 @@ --target-dir <DIRECTORY> Directory for all generated artifacts - --out-dir <PATH> Copy final artifacts to this directory (unstable) + --artifact-dir <PATH> Copy final artifacts to this directory (unstable) --build-plan Output the build plan in JSON (unstable) diff --git a/tests/testsuite/collisions.rs b/tests/testsuite/collisions.rs index b615f713e95..0f1cdf20051 100644 --- a/tests/testsuite/collisions.rs +++ b/tests/testsuite/collisions.rs @@ -96,10 +96,10 @@ This may become a hard error in the future; see