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

[valadaptive]

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.

Existing users of the --out-dir argument and out-dir config.toml key will be redirected to --artifact-dir via a warning message.

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.

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?

--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.

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.

[rustbot]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @epage (or someone else) some time within the next two weeks.

Please see the contribution instructions for more information. Namely, in order to ensure the minimum review times lag, PR authors and assigned reviewers should ensure that the review label (S-waiting-on-review and S-waiting-on-author) stays updated, invoking these commands when appropriate:

• @rustbot author: the review is finished, PR author should check the comments and take action accordingly
• @rustbot review: the author is ready for a review, this PR will be queued again in the reviewer's queue

[workingjubilee]

Grim news. Perhaps both flags must be briefly supported to deal with the bootstrap problem.

[valadaptive]

Never mind; it seems I was a bit zealous in replacing --out-dir and accidentally search-and-replaced it in some rustc invocations. Might still need to do some fixups but we're looking a lot better now.

[valadaptive]

This should be ready for review now. Not sure if this needs to go through any sort of design process since it's renaming a nightly-only API. There does seem to be some consensus in #6790 that --artifact-dir is a better name.