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

@@ -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(())
 }

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<RefCell<Option<RustfixDiagnosticServer>>>,
-    /// 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<PathBuf>,
     /// `true` to output a future incompatibility report at the end of the build
     pub future_incompat_report: bool,

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<PathBuf>,
-    /// 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<PathBuf>,
     /// 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<PathBuf> {
         self.export_dir.clone()
     }

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\
                              {}",

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),
+        )
     }
 }
 

src/cargo/util/context/mod.rs

@@ -2609,7 +2609,9 @@ pub struct CargoBuildConfig {
     pub rustc_workspace_wrapper: Option<ConfigRelativePath>,
     pub rustc: Option<ConfigRelativePath>,
     pub rustdoc: Option<ConfigRelativePath>,
+    // deprecated alias for artifact-dir
     pub out_dir: Option<ConfigRelativePath>,
+    pub artifact_dir: Option<ConfigRelativePath>,
 }
 
 /// Configuration for `build.target`.

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

src/doc/man/generated_txt/cargo-build.txt

@@ -188,7 +188,7 @@ OPTIONS
            <https://doc.rust-lang.org/cargo/reference/config.html>. 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

src/doc/src/commands/cargo-build.md

@@ -222,7 +222,7 @@ specified with the <code>CARGO_TARGET_DIR</code> environment variable, or the
 Defaults to <code>target</code> in the root of the workspace.</dd>
 
 
-<dt class="option-term" id="option-cargo-build---out-dir"><a class="option-anchor" href="#option-cargo-build---out-dir"></a><code>--out-dir</code> <em>directory</em></dt>
+<dt class="option-term" id="option-cargo-build---artifact-dir"><a class="option-anchor" href="#option-cargo-build---artifact-dir"></a><code>--artifact-dir</code> <em>directory</em></dt>
 <dd class="option-desc">Copy final artifacts to this directory.</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>

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

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

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::<Vec<_>>();
     expected.sort_unstable();
     assert_eq!(actual, expected);

tests/testsuite/cargo_build/help/stdout.term.svg

@@ -109,7 +109,7 @@
 </tspan>
     <tspan x="10px" y="820px"><tspan>      </tspan><tspan class="fg-cyan bold">--target-dir</tspan><tspan class="fg-cyan"> </tspan><tspan class="fg-cyan">&lt;DIRECTORY&gt;</tspan><tspan>  Directory for all generated artifacts</tspan>
 </tspan>
-    <tspan x="10px" y="838px"><tspan>      </tspan><tspan class="fg-cyan bold">--out-dir</tspan><tspan class="fg-cyan"> </tspan><tspan class="fg-cyan">&lt;PATH&gt;</tspan><tspan>          Copy final artifacts to this directory (unstable)</tspan>
+    <tspan x="10px" y="838px"><tspan>      </tspan><tspan class="fg-cyan bold">--artifact-dir</tspan><tspan class="fg-cyan"> </tspan><tspan class="fg-cyan">&lt;PATH&gt;</tspan><tspan>     Copy final artifacts to this directory (unstable)</tspan>
 </tspan>
     <tspan x="10px" y="856px"><tspan>      </tspan><tspan class="fg-cyan bold">--build-plan</tspan><tspan>              Output the build plan in JSON (unstable)</tspan>
 </tspan>

tests/testsuite/collisions.rs

@@ -96,10 +96,10 @@ This may become a hard error in the future; see <https://github.com/rust-lang/ca
 // See https://github.com/rust-lang/cargo/issues/7493
 #[cfg_attr(
     any(target_env = "msvc", target_vendor = "apple"),
-    ignore = "--out-dir and examples are currently broken on MSVC and apple"
+    ignore = "--artifact-dir and examples are currently broken on MSVC and apple"
 )]
 fn collision_export() {
-    // `--out-dir` combines some things which can cause conflicts.
+    // `--artifact-dir` combines some things which can cause conflicts.
     let p = project()
         .file("Cargo.toml", &basic_manifest("foo", "1.0.0"))
         .file("examples/foo.rs", "fn main() {}")
@@ -108,10 +108,10 @@ fn collision_export() {
 
     // -j1 to avoid issues with two processes writing to the same file at the
     // same time.
-    p.cargo("build -j1 --out-dir=out -Z unstable-options --bins --examples")
-        .masquerade_as_nightly_cargo(&["out-dir"])
+    p.cargo("build -j1 --artifact-dir=out -Z unstable-options --bins --examples")
+        .masquerade_as_nightly_cargo(&["artifact-dir"])
         .with_stderr_contains("\
-[WARNING] `--out-dir` filename collision.
+[WARNING] `--artifact-dir` filename collision.
 The example target `foo` in package `foo v1.0.0 ([..]/foo)` has the same output filename as the bin target `foo` in package `foo v1.0.0 ([..]/foo)`.
 Colliding filename is: [..]/foo/out/foo[EXE]
 The exported filenames should be unique.

tests/testsuite/main.rs

@@ -8,6 +8,7 @@ extern crate cargo_test_macro;
 mod advanced_env;
 mod alt_registry;
 mod artifact_dep;
+mod artifact_dir;
 mod bad_config;
 mod bad_manifest_path;
 mod bench;
@@ -129,7 +130,6 @@ mod new;
 mod offline;
 mod old_cargos;
 mod open_namespaces;
-mod out_dir;
 mod owner;
 mod package;
 mod package_features;