Skip to content

Commit 07f16bb

Browse files
sslime336tshepang
authored andcommitted
Try to avoid confusion
1 parent 8648005 commit 07f16bb

File tree

1 file changed

+29
-22
lines changed

1 file changed

+29
-22
lines changed

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

+29-22
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,31 @@ if you want to learn more about `x.py`, [read this chapter][bootstrap].
5757

5858
[bootstrap]: ./bootstrapping.md
5959

60+
Also, using `x` rather than `x.py` is recommended as:
61+
62+
> `./x` is the most likely to work on every system (on Unix it runs the shell script
63+
> that does python version detection, on Windows it will probably run the
64+
> powershell script - certainly less likely to break than `./x.py` which often just
65+
> opens the file in an editor).[^1]
66+
67+
(You can find the platform related scripts around the `x.py`, like `x.ps1`)
68+
69+
Notice that this is not absolute, for instance, using Nushell in VSCode on Win10,
70+
typing `x` or `./x` still open the `x.py` in editor rather invoke the program :)
71+
72+
In the rest of documents, we use `x` to represent the straightly usage of `x.py`, which
73+
means the following command:
74+
75+
```bash
76+
./x check
77+
```
78+
79+
could be replaced by:
80+
81+
```bash
82+
./x.py check
83+
```
84+
6085
### Running `x.py`
6186

6287
The `x.py` command can be run directly on most Unix systems in the following format:
@@ -108,28 +133,10 @@ of a checkout. It also looks up the appropriate version of `python` to use.
108133

109134
You can install it with `cargo install --path src/tools/x`.
110135

111-
Using `x` rather than `x.py` is recommended as:
112-
113-
> `./x` is the most likely to work on every system (on Unix it runs the shell script
114-
> that does python version detection, on Windows it will probably run the
115-
> powershell script - certainly less likely to break than `./x.py` which often just
116-
> opens the file in an editor).[^1]
117-
118-
Notice that this is not absolute, for instance, using Nushell in VSCode on Win10,
119-
typing `x` or `./x` still open the `x.py` in editor rather invoke the program :)
120-
121-
In the rest of documents, we use `x` to represent the straightly usage of `x.py`, which
122-
means the following command:
123-
124-
```bash
125-
./x check
126-
```
127-
128-
could be replaced by:
129-
130-
```bash
131-
./x.py check
132-
```
136+
To clarify that this is another global installed binary util, which is
137+
similar to the fromer `x` declared in section [What is `x.py`](#what-is-xpy) but
138+
it works as an independent process to execute the `x.py` rather than calling the
139+
shell to run the platform related scripts.
133140

134141
## Create a `config.toml`
135142

0 commit comments

Comments
 (0)