Change x.py into x, add explanation for x

Author: sslime336

src/building/bootstrapping.md

@@ -107,7 +107,7 @@ to be identical to before, unless something has broken.
 
 ### Building the stages
 
-`x.py` tries to be helpful and pick the stage you most likely meant for each subcommand.
+`x` tries to be helpful and pick the stage you most likely meant for each subcommand.
 These defaults are as follows:
 
 - `check`: `--stage 0`
@@ -152,7 +152,7 @@ bootstrapping the compiler.
 
 This is a detailed look into the separate bootstrap stages.
 
-The convention `x.py` uses is that:
+The convention `x` uses is that:
 
 - A `--stage N` flag means to run the stage N compiler (`stageN/rustc`).
 - A "stage N artifact" is a build artifact that is _produced_ by the stage N compiler.
@@ -161,7 +161,7 @@ The convention `x.py` uses is that:
 
 #### Build artifacts
 
-Anything you can build with `x.py` is a _build artifact_.
+Anything you can build with `x` is a _build artifact_.
 Build artifacts include, but are not limited to:
 
 - binaries, like `stage0-rustc/rustc-main`
@@ -243,7 +243,7 @@ artifacts into the appropriate place, skipping the cargo invocation.
 For instance, you might want to build an ARM version of rustc using an x86 machine.
 Building stage2 `std` is different when you are cross-compiling.
 
-This is because `x.py` uses a trick: if `HOST` and `TARGET` are the same,
+This is because `x` uses a trick: if `HOST` and `TARGET` are the same,
 it will reuse stage1 `std` for stage2! This is sound because stage1 `std`
 was compiled with the stage1 compiler, i.e. a compiler using the source code
 you currently have checked out. So it should be identical (and therefore ABI-compatible)
@@ -362,7 +362,7 @@ You can find more discussion about sysroots in:
 
 ## Passing flags to commands invoked by `bootstrap`
 
-`x.py` allows you to pass stage-specific flags to `rustc` and `cargo` when bootstrapping.
+`x` allows you to pass stage-specific flags to `rustc` and `cargo` when bootstrapping.
 The `RUSTFLAGS_BOOTSTRAP` environment variable is passed as `RUSTFLAGS` to the bootstrap stage
 (stage0), and `RUSTFLAGS_NOT_BOOTSTRAP` is passed when building artifacts for later stages.
 `RUSTFLAGS` will work, but also affects the build of `bootstrap` itself, so it will be rare to want
@@ -395,7 +395,7 @@ If `./stageN/bin/rustc` gives an error about environment variables, that
 usually means something is quite wrong -- or you're trying to compile e.g.
 `rustc` or `std` or something that depends on environment variables. In
 the unlikely case that you actually need to invoke rustc in such a situation,
-you can tell the bootstrap shim to print all env variables by adding `-vvv` to your `x.py` command.
+you can tell the bootstrap shim to print all env variables by adding `-vvv` to your `x` command.
 
 Finally, bootstrap makes use of the [cc-rs crate] which has [its own
 method][env-vars] of configuring C compilers and C flags via environment
@@ -408,7 +408,7 @@ variables.
 
 In this part, we will investigate the build command's stdout in an action
 (similar, but more detailed and complete documentation compare to topic above).
-When you execute `x.py build --dry-run` command, the build output will be something
+When you execute `x build --dry-run` command, the build output will be something
 like the following:
 
 ```text

src/building/compiler-documenting.md

@@ -36,7 +36,7 @@ like the standard library (std) or the compiler (rustc).
 - Document internal rustc items
 
   Compiler documentation is not built by default.
-  To create it by default with `x.py doc`, modify `config.toml`:
+  To create it by default with `x doc`, modify `config.toml`:
 
   ```toml
   [build]

src/building/how-to-build-and-run.md

@@ -108,6 +108,29 @@ of a checkout. It also looks up the appropriate version of `python` to use.
 
 You can install it with `cargo install --path src/tools/x`.
 
+Using `x` rather than `x.py` is recommended as:
+
+> `./x` is the most likely to work on every system (on Unix it runs the shell script
+> that does python version detection, on Windows it will probably run the
+> powershell script - certainly less likely to break than `./x.py` which often just
+> opens the file in an editor).[^1]
+
+Notice that this is not absolute, for instance, using Nushell in VSCode on Win10,
+typing `x` or `./x` still open the `x.py` in editor rather invoke the program :)
+
+In the rest of documents, we use `x` to represent the straightly usage of `x.py`, which
+means the following command:
+
+```bash
+./x check
+```
+
+could been replaced by:
+
+```bash
+./x.py check
+```
+
 ## Create a `config.toml`
 
 To start, run `./x setup` and select the `compiler` defaults. This will do some initialization
@@ -123,9 +146,9 @@ If you have already built `rustc` and you change settings related to LLVM, then
 execute `rm -rf build` for subsequent configuration changes to take effect. Note that `./x
 clean` will not cause a rebuild of LLVM.
 
-## Common `x.py` commands
+## Common `x` commands
 
-Here are the basic invocations of the `x.py` commands most commonly used when
+Here are the basic invocations of the `x` commands most commonly used when
 working on `rustc`, `std`, `rustdoc`, and other tools.
 
 | Command     | When to use it                                                                                               |
@@ -141,9 +164,9 @@ serious development work. In particular, `./x build` and `./x test`
 provide many ways to compile or test a subset of the code, which can save a lot
 of time.
 
-Also, note that `x.py` supports all kinds of path suffixes for `compiler`, `library`,
-and `src/tools` directories. So, you can simply run `x.py test tidy` instead of
-`x.py test src/tools/tidy`. Or, `x.py build std` instead of `x.py build library/std`.
+Also, note that `x` supports all kinds of path suffixes for `compiler`, `library`,
+and `src/tools` directories. So, you can simply run `x test tidy` instead of
+`x test src/tools/tidy`. Or, `x build std` instead of `x build library/std`.
 
 [rust-analyzer]: suggested.html#configuring-rust-analyzer-for-rustc
 
@@ -156,7 +179,7 @@ Note that building will require a relatively large amount of storage space.
 You may want to have upwards of 10 or 15 gigabytes available to build the compiler.
 
 Once you've created a `config.toml`, you are now ready to run
-`x.py`. There are a lot of options here, but let's start with what is
+`x`. There are a lot of options here, but let's start with what is
 probably the best "go to" command for building a local compiler:
 
 ```bash
@@ -206,7 +229,7 @@ Instead, you can just build using the bootstrap compiler.
 ./x build --stage 0 library
 ```
 
-If you choose the `library` profile when running `x.py setup`, you can omit `--stage 0` (it's the
+If you choose the `library` profile when running `x setup`, you can omit `--stage 0` (it's the
 default).
 
 ## Creating a rustup toolchain
@@ -241,7 +264,7 @@ LLVM version: 11.0
 ```
 
 The rustup toolchain points to the specified toolchain compiled in your `build` directory,
-so the rustup toolchain will be updated whenever `x.py build` or `x.py test` are run for
+so the rustup toolchain will be updated whenever `x build` or `x test` are run for
 that toolchain/stage.
 
 **Note:** the toolchain we've built does not include `cargo`.  In this case, `rustup` will
@@ -262,7 +285,7 @@ want to build this component:
 ## Building targets for cross-compilation
 
 To produce a compiler that can cross-compile for other targets,
-pass any number of `target` flags to `x.py build`.
+pass any number of `target` flags to `x build`.
 For example, if your host platform is `x86_64-unknown-linux-gnu`
 and your cross-compilation target is `wasm32-wasi`, you can build with:
 
@@ -274,7 +297,7 @@ Note that if you want the resulting compiler to be able to build crates that
 involve proc macros or build scripts, you must be sure to explicitly build target support for the
 host platform (in this case, `x86_64-unknown-linux-gnu`).
 
-If you want to always build for other targets without needing to pass flags to `x.py build`,
+If you want to always build for other targets without needing to pass flags to `x build`,
 you can configure this in the `[build]` section of your `config.toml` like so:
 
 ```toml
@@ -303,9 +326,9 @@ then once you have built your compiler you will be able to use it to cross-compi
 cargo +stage1 build --target wasm32-wasi
 ```
 
-## Other `x.py` commands
+## Other `x` commands
 
-Here are a few other useful `x.py` commands. We'll cover some of them in detail
+Here are a few other useful `x` commands. We'll cover some of them in detail
 in other sections:
 
 - Building things:
@@ -335,3 +358,5 @@ everything up then you only need to run one command!
 
 `rm -rf build` works too, but then you have to rebuild LLVM, which can take
 a long time even on fast computers.
+
+[^1]: issue[#1707](https://github.com/rust-lang/rustc-dev-guide/issues/1707)

src/building/suggested.md

@@ -26,15 +26,15 @@ You can also install the hook as a step of running `./x setup`!
 `rust-analyzer` can help you check and format your code whenever you save
 a file. By default, `rust-analyzer` runs the `cargo check` and `rustfmt`
 commands, but you can override these commands to use more adapted versions
-of these tools when hacking on `rustc`. For example, `x.py setup vscode` will prompt
+of these tools when hacking on `rustc`. For example, `x setup vscode` will prompt
 you to create a `.vscode/settings.json` file which will configure Visual Studio code.
 This will ask `rust-analyzer` to use `./x check` to check the sources, and the
 stage 0 rustfmt to format them.
 The recommended `rust-analyzer` settings live at [`src/etc/rust_analyzer_settings.json`].
 
-If you have enough free disk space and you would like to be able to run `x.py` commands while
+If you have enough free disk space and you would like to be able to run `x` commands while
 rust-analyzer runs in the background, you can also add `--build-dir build-rust-analyzer` to the
-`overrideCommand` to avoid x.py locking.
+`overrideCommand` to avoid x locking.
 
 If you're running `coc.nvim`, you can use `:CocLocalConfig` to create a
 `.vim/coc-settings.json` and copy the settings from [`src/etc/rust_analyzer_settings.json`].
@@ -73,7 +73,7 @@ Rust-Analyzer to already be configured with Neovim. Steps for this can be
 [found here](https://rust-analyzer.github.io/manual.html#nvim-lsp).
 
 1. First install the plugin. This can be done by following the steps in the README.
-2. Run `x.py setup`, which will have a prompt for it to create a `.vscode/settings.json` file.
+2. Run `x setup`, which will have a prompt for it to create a `.vscode/settings.json` file.
    `neoconf` is able to read and update Rust-Analyzer settings automatically when the project is
    opened when this file is detected.
 
@@ -141,11 +141,11 @@ directories you have [setup a worktree for]. You may need to use the pinned
 nightly version from `src/stage0.json`, but often the normal `nightly` channel
 will work.
 
-**Note** see [the section on vscode] for how to configure it with this real rustfmt `x.py` uses,
+**Note** see [the section on vscode] for how to configure it with this real rustfmt `x` uses,
 and [the section on rustup] for how to setup `rustup` toolchain for your bootstrapped compiler
 
 **Note** This does _not_ allow you to build `rustc` with cargo directly. You
-still have to use `x.py` to work on the compiler or standard library, this just
+still have to use `x` to work on the compiler or standard library, this just
 lets you use `cargo fmt`.
 
 [installing a nightly toolchain]: https://rust-lang.github.io/rustup/concepts/channels.html?highlight=nightl#working-with-nightly-rust

src/git.md

@@ -139,7 +139,7 @@ You might also notice conflicts in the web UI:
 ![conflict in src/tools/cargo](./img/submodule-conflicts.png)
 
 The most common cause is that you rebased after a change and ran `git add .` without first running
-`x.py` to update the submodules.  Alternatively, you might have run `cargo fmt` instead of `x fmt`
+`x` to update the submodules.  Alternatively, you might have run `cargo fmt` instead of `x fmt`
 and modified files in a submodule, then committed the changes.
 
 To fix it, do the following things:
@@ -248,7 +248,7 @@ out if you're using `download-ci-llvm`.  To avoid having to keep fetching its hi
 
 Note that, as of <!-- date-check --> Aug 2022,
 there is a [bug][#77620] if you use worktrees,
-submodules, and `x.py` in a commit hook.
+submodules, and `x` in a commit hook.
 If you run into an error like the following,
 it's not anything you did wrong:
 
@@ -314,7 +314,7 @@ Generally, resolving the conflict consists of two steps: First, fix the
 particular conflict. Edit the file to make the changes you want and remove the
 `<<<<<<<`, `=======` and `>>>>>>>` lines in the process. Second, check the
 surrounding code. If there was a conflict, its likely there are some logical
-errors lying around too! It's a good idea to run `x.py check` here to make sure
+errors lying around too! It's a good idea to run `x check` here to make sure
 there are no glaring errors.
 
 Once you're all done fixing the conflicts, you need to stage the files that had
@@ -558,7 +558,7 @@ commit, which doesn't change unless modified manually. If you use `git checkout
 in the `llvm-project` directory and go back to the `rust` directory, you can stage this
 change like any other, e.g. by running `git add src/llvm-project`. (Note that if
 you *don't* stage the change to commit, then you run the risk that running
-`x.py` will just undo your change by switching back to the previous commit when
+`x` will just undo your change by switching back to the previous commit when
 it automatically "updates" the submodules.)
 
 This version selection is usually done by the maintainers of the project, and

src/profiling.md

@@ -41,7 +41,7 @@ extension in LLVM bitcode format.
 Example usage:
 ```
 cargo install cargo-llvm-lines
-# On a normal crate you could now run `cargo llvm-lines`, but `x.py` isn't normal :P
+# On a normal crate you could now run `cargo llvm-lines`, but `x` isn't normal :P
 
 # Do a clean before every run, to not mix in the results from previous runs.
 ./x clean

src/profiling/wpa_profiling.md

@@ -47,11 +47,11 @@ we'll need to build a stage 1 compiler and then a stage 2 compiler ourselves.
 To do this, make sure you have set `debuginfo-level = 1` in your `config.toml` file. This tells
 rustc to generate debug information which includes stack frames when bootstrapping.
 
-Now you can build the stage 1 compiler: `python x.py build --stage 1 -i library` or however
+Now you can build the stage 1 compiler: `x build --stage 1 -i library` or however
 else you want to build the stage 1 compiler.
 
 Now that the stage 1 compiler is built, we can record the stage 2 build. Go back to WPR, click the
-"start" button and build the stage 2 compiler (e.g., `python x build --stage=2 -i library`).
+"start" button and build the stage 2 compiler (e.g., `x build --stage=2 -i library`).
 When this process finishes, stop the recording.
 
 Click the Save button and once that process is complete, click the "Open in WPA" button which

src/rustdoc.md

@@ -41,7 +41,7 @@ does is call the `main()` that's in this crate's `lib.rs`, though.)
 
 ## Cheat sheet
 
-* Run `./x setup tools` before getting started. This will configure `x.py`
+* Run `./x setup tools` before getting started. This will configure `x`
   with nice settings for developing rustdoc and other tools, including
   downloading a copy of rustc rather than building it.
 * Use `./x check src/tools/rustdoc` to quickly check for compile errors.

src/tests/compiletest.md

@@ -330,7 +330,7 @@ set a baseline for optimizations:
 
 The test should be annotated with `// EMIT_MIR` comments that specify files that
 will contain the expected MIR output.
-You can use `x.py test --bless` to create the initial expected files.
+You can use `x test --bless` to create the initial expected files.
 
 There are several forms the `EMIT_MIR` comment can take:
 

src/tests/headers.md

@@ -145,7 +145,7 @@ The following header commands will check rustc build settings and target setting
   (AddressSanitizer, hardware-assisted AddressSanitizer, LeakSanitizer,
   MemorySanitizer or ThreadSanitizer respectively)
 * `needs-run-enabled` — ignores if it is a test that gets executed, and
-  running has been disabled. Running tests can be disabled with the `x.py test
+  running has been disabled. Running tests can be disabled with the `x test
   --run=never` flag, or running on fuchsia.
 * `needs-unwind` — ignores if the target does not support unwinding
 * `needs-rust-lld` — ignores if the rust lld support is not enabled

src/tests/intro.md

@@ -29,7 +29,7 @@ The [Compiletest chapter][compiletest] goes into detail on how to use this tool.
 The standard library and many of the compiler packages include typical Rust `#[test]`
 unit tests, integration tests, and documentation tests.
 You can pass a path to `x.py` to almost any package in the `library` or `compiler` directory,
-and `x.py` will essentially run `cargo test` on that package.
+and `x` will essentially run `cargo test` on that package.
 
 Examples:
 

src/tests/running.md

@@ -2,7 +2,7 @@
 
 <!-- toc -->
 
-You can run the tests using `x.py`. The most basic command – which
+You can run the tests using `x`. The most basic command – which
 you will almost never want to use! – is as follows:
 
 ```bash
@@ -122,7 +122,7 @@ But unfortunately, it's impossible. You should invoke following instead:
 Another common thing that people want to do is to run an **individual
 test**, often the test they are trying to fix. As mentioned earlier,
 you may pass the full file path to achieve this, or alternatively one
-may invoke `x.py` with the `--test-args` option:
+may invoke `x` with the `--test-args` option:
 
 ```bash
 ./x test tests/ui --test-args issue-1234
@@ -247,7 +247,7 @@ pong
 ```
 
 To run tests using the remote runner, set the `TEST_DEVICE_ADDR` environment
-variable then use `x.py` as usual. For example, to run `ui` tests for a RISC-V
+variable then use `x` as usual. For example, to run `ui` tests for a RISC-V
 machine with the IP address `1.2.3.4` use
 ```sh
 export TEST_DEVICE_ADDR="1.2.3.4:12345"
@@ -273,7 +273,7 @@ run "/tmp/work/test1018/a"
 [...]
 ```
 
-Tests are built on the machine running `x.py` not on the remote machine. Tests
+Tests are built on the machine running `x` not on the remote machine. Tests
 which fail to build unexpectedly (or `ui` tests producing incorrect build
 output) may fail without ever running on the remote machine.
 

src/tests/ui.md

@@ -485,7 +485,7 @@ Then, it applies the suggestion and compares against `.fixed` (they must match).
 Finally, the fixed source is compiled, and this compilation is required to succeed.
 
 Usually when creating a rustfix test you will generate the `.fixed` file
-automatically with the `x.py test --bless` option.
+automatically with the `x test --bless` option.
 
 The `run-rustfix` header will cause *all* suggestions to be applied, even
 if they are not [`MachineApplicable`](../diagnostics.md#suggestions).