You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: Contributing.md
+62-17
Original file line number
Diff line number
Diff line change
@@ -14,40 +14,77 @@ Conduct](CODE_OF_CONDUCT.md).
14
14
Rustfmt requires a nightly compiler. Replace all invocations of `cargo` by
15
15
`cargo +nightly` if necessary.
16
16
17
-
At all times the environment variables `CFG_RELEASE_CHANNEL` and `CFG_RELEASE` must
18
-
be set to either `nightly` or `beta`. Both should be set to the same value. The
19
-
project supports [cargo-make](https://github.com/sagiegurari/cargo-make) which
20
-
automatically sets these variables for you:
17
+
At all times the environment variables `CFG_RELEASE_CHANNEL` and `CFG_RELEASE` must be set. The
18
+
project supports and recommends [cargo-make][cargo-make] when working on rustfmt because `cargo-make` automatically sets these variables for you and simplifies the process.
21
19
20
+
The available tasks for `cargo-make` are listed in `Makefile.toml` and several are detailed in sections below.
21
+
22
+
You can alternatively use `cargo` directly, but to do so you'll have to manually set the `CFG_RELEASE` and `CFG_RELEASE_CHANNEL` environment variables yourself and also provide the corresponding features.
23
+
24
+
`CFG_RELEASE_CHANNEL` must be set to either `nightly` or `beta`, and `CFG_RELEASE` should be set to your corresponding Rust version.
25
+
26
+
For example:
27
+
```sh
28
+
export CFG_RELEASE=1.45.0-nightly
29
+
export CFG_RELEASE=nightly
30
+
cargo +nightly build ...
31
+
# And/or inline if you prefer, or need to override value(s)
It would be really useful to have people use rustfmt on their projects and file
31
53
issues where it does something you don't expect.
32
54
33
55
34
-
## Create test cases
56
+
## Running tests
35
57
36
-
Having a strong test suite for a tool like this is essential. It is very easy
37
-
to create regressions. Any tests you can add are very much appreciated.
58
+
The tests can be executed with `cargo make` or directly with `cargo` provided the corresponding environment variables have been set.
59
+
60
+
To run tests with `cargo make`:
61
+
62
+
```sh
63
+
cargo make test
64
+
```
65
+
66
+
Or alternatively with `cargo` directly:
67
+
```sh
68
+
cargo test --all-features
69
+
# And/or with the required environment variables inline if you prefer, or need to override the value(s)
70
+
CFG_RELEASE_CHANNEL=beta CFG_RELEASE=1.45.0-nightly cargo test --all-features
71
+
```
38
72
39
-
The tests can be run with `cargo make test`. This does a number of things:
73
+
This does a number of things:
40
74
* runs the unit tests for a number of internal functions;
41
-
* makes sure that rustfmt run on every file in `rustfmt-core/rustfmt-lib/tests/source/`
42
-
is equal to its associated file in `rustfmt-core/rustfmt-lib/tests/target/`;
43
-
* runs idempotence tests on the files in `rustfmt-core/rustfmt-lib/tests/target/`.
75
+
* ensures that rustfmt is executed against every file in `tests/source/` and that each formatted result is equal to its associated file in `tests/target/`;
76
+
* runs idempotence tests on the files in `tests/target/`.
44
77
These files should not be changed by rustfmt;
45
78
* checks that rustfmt's code is not changed by running on itself. This ensures
46
79
that the project bootstraps.
47
80
81
+
## Creating test cases
82
+
Having a strong test suite for a tool like this is essential. It is very easy
83
+
to create regressions. Any tests you can add are very much appreciated.
84
+
48
85
Creating a test is as easy as creating a new file in
49
-
`rustfmt-core/rustfmt-lib/tests/source/` and an equally named one in
50
-
`rustfmt-core/rustfmt-lib/tests/target/`. If it is only required that rustfmt leaves a
86
+
`tests/source/` and an equally named one in
87
+
`tests/target/`. If it is only required that rustfmt leaves a
51
88
piece of code unformatted, it may suffice to only create a target file.
52
89
53
90
Whenever there's a discrepancy between the expected output when running tests, a
@@ -73,6 +110,8 @@ would need a configuration file named `test-indent.toml` in that directory. As a
73
110
example, the `issue-1111.rs` test file is configured by the file
Some `rewrite_*` methods use the `debug!` macro for printing useful information.
@@ -82,7 +121,13 @@ and get a better grasp on the execution flow.
82
121
83
122
## Hack!
84
123
85
-
Here are some [good starting issues](https://github.com/rust-lang/rustfmt/issues?q=is%3Aopen+is%3Aissue+label%3Agood-first-issue).
124
+
There are a lot of open issues on the backlog for those interested in hacking on rustfmt. If you find an issue that you are interested in working on, add a comment to the issue to let us (and other potential contributors) know!
(Windows users can use `set` to specify the environment variable values)
90
101
91
102
This will install `rustfmt` in your `~/.cargo/bin`. Make sure to add `~/.cargo/bin` directory to
92
103
your PATH variable.
@@ -146,9 +157,42 @@ for more info.
146
157
147
158
## How to build and test
148
159
149
-
`cargo build` to build.
160
+
We recommend using [cargo make][cargo-make] when working with the rustfmt codebase.
161
+
162
+
You can alternatively use `cargo` directly, but you'll have to set the `CFG_RELEASE` and `CFG_RELEASE_CHANNEL` environment variables and also provide the corresponding features.
163
+
164
+
For example:
165
+
```sh
166
+
export CFG_RELEASE=1.45.0-nightly
167
+
export CFG_RELEASE=nightly
168
+
```
169
+
(Windows users can use `set` to specify the environment variable values)
0 commit comments