Auto merge of #13809 - valadaptive:artifact-dir, r=epage

Rename --out-dir to --artifact-dir

Progress towards unblocking #6790. Renames the experimental `--out-dir` argument to `--artifact-dir`, both to reflect that it's where the final build *artifacts* will be copied to, and to avoid confusion with the `OUT_DIR` environment variable which serves an entirely different purpose.

For transition purposes, `--out-dir` argument and `out-dir` config key will still work with a deprecation message encouraging the use of the new arg and config key.

### Rationale

A lot of people seem to be confused by the naming of the `--out-dir` argument, and are misled into thinking it serves the same purpose as the `OUT_DIR` environment variable:

> [However, it doesn't seem that OUT_DIR environment variable is set to the value of --out-dir when build.rs is executed.](#6790 (comment))

> [I understand that the worry is that there could be confusion between --out-dir for cargo and the environment variable OUT_DIR for build.rs, but doesn't it mean exactly the same in both cases?](#6790 (comment))

> [--out-dir: Things will be built into $PWD/target as normal, but copies some of the artifacts into the directory specified by out-dir (not a profile specific subdirectory). Unstable flag, added in March 2018. cargo build --out-dir #5203 Ability to specify output artifact name #4875. **Mimicks the behavior of OUT_DIR.**](#6100 (comment))

> [I recently had a couple of people express an interest in --out-dir being stabilized and from my initial digging it seems like what they may actually want is to switch to OUT_DIR, which is already stable.](#6100 (comment))

Author: bors

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