Skip to content

docs: update dev instructions and unstable opts info #4250

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jun 12, 2020
Merged

docs: update dev instructions and unstable opts info #4250

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ea864d4
docs: update build/test/install instructions
calebcartwright Jun 10, 2020
1d72969
docs: correct unstable opts descr. in readme
calebcartwright Jun 11, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 62 additions & 17 deletions Contributing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,40 +14,77 @@ Conduct](CODE_OF_CONDUCT.md).
Rustfmt requires a nightly compiler. Replace all invocations of `cargo` by
`cargo +nightly` if necessary.

At all times the environment variables `CFG_RELEASE_CHANNEL` and `CFG_RELEASE` must
be set to either `nightly` or `beta`. Both should be set to the same value. The
project supports [cargo-make](https://github.com/sagiegurari/cargo-make) which
automatically sets these variables for you:
At all times the environment variables `CFG_RELEASE_CHANNEL` and `CFG_RELEASE` must be set. The
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.

The available tasks for `cargo-make` are listed in `Makefile.toml` and several are detailed in sections below.

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.

`CFG_RELEASE_CHANNEL` must be set to either `nightly` or `beta`, and `CFG_RELEASE` should be set to your corresponding Rust version.

For example:
```sh
export CFG_RELEASE=1.45.0-nightly
export CFG_RELEASE=nightly
cargo +nightly build ...
# And/or inline if you prefer, or need to override value(s)
CFG_RELEASE_CHANNEL=nightly CFG_RELEASE=1.45.0-nightly cargo +nightly build ...
```
cargo +nightly make test
(Windows users can use `set` to specify the environment variable values)

## Building
To build with `cargo make`:

```sh
cargo make build
```

The available tasks are listed in `Makefile.toml`.
Or alternatively with `cargo` directly:
```sh
cargo build --all-features
# And/or with the required environment variables inline if you prefer, or need to override the value(s)
CFG_RELEASE_CHANNEL=nightly CFG_RELEASE=1.45.0-nightly cargo build --all-features
```

## Test and file issues

It would be really useful to have people use rustfmt on their projects and file
issues where it does something you don't expect.


## Create test cases
## Running tests

Having a strong test suite for a tool like this is essential. It is very easy
to create regressions. Any tests you can add are very much appreciated.
The tests can be executed with `cargo make` or directly with `cargo` provided the corresponding environment variables have been set.

To run tests with `cargo make`:

```sh
cargo make test
```

Or alternatively with `cargo` directly:
```sh
cargo test --all-features
# And/or with the required environment variables inline if you prefer, or need to override the value(s)
CFG_RELEASE_CHANNEL=beta CFG_RELEASE=1.45.0-nightly cargo test --all-features
```

The tests can be run with `cargo make test`. This does a number of things:
This does a number of things:
* runs the unit tests for a number of internal functions;
* makes sure that rustfmt run on every file in `rustfmt-core/rustfmt-lib/tests/source/`
is equal to its associated file in `rustfmt-core/rustfmt-lib/tests/target/`;
* runs idempotence tests on the files in `rustfmt-core/rustfmt-lib/tests/target/`.
* 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/`;
* runs idempotence tests on the files in `tests/target/`.
These files should not be changed by rustfmt;
* checks that rustfmt's code is not changed by running on itself. This ensures
that the project bootstraps.

## Creating test cases
Having a strong test suite for a tool like this is essential. It is very easy
to create regressions. Any tests you can add are very much appreciated.

Creating a test is as easy as creating a new file in
`rustfmt-core/rustfmt-lib/tests/source/` and an equally named one in
`rustfmt-core/rustfmt-lib/tests/target/`. If it is only required that rustfmt leaves a
`tests/source/` and an equally named one in
`tests/target/`. If it is only required that rustfmt leaves a
piece of code unformatted, it may suffice to only create a target file.

Whenever there's a discrepancy between the expected output when running tests, a
Expand All @@ -73,6 +110,8 @@ would need a configuration file named `test-indent.toml` in that directory. As a
example, the `issue-1111.rs` test file is configured by the file
`./tests/config/issue-1111.toml`.

[cargo-make]: https://sagiegurari.github.io/cargo-make/

## Debugging

Some `rewrite_*` methods use the `debug!` macro for printing useful information.
Expand All @@ -82,7 +121,13 @@ and get a better grasp on the execution flow.

## Hack!

Here are some [good starting issues](https://github.com/rust-lang/rustfmt/issues?q=is%3Aopen+is%3Aissue+label%3Agood-first-issue).
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!

Here are some good starting issues:

[![GitHub good-first-issue](https://img.shields.io/github/issues/rust-lang/rustfmt/good-first-issue?style=flat-square)](https://github.com/rust-lang/rustfmt/issues?q=is%3Aopen+is%3Aissue+label%3Agood%20first%20issue)
[![GitHub help-wanted](https://img.shields.io/github/issues/rust-lang/rustfmt/help-wanted?style=flat-square)](https://github.com/rust-lang/rustfmt/issues?q=is%3Aopen+is%3Aissue+label%3Ahelp-wanted)


If you've found areas which need polish and don't have issues, please submit a
PR, don't feel there needs to be an issue.
Expand All @@ -95,7 +140,7 @@ source code. So, basically, the only style guideline is that you must pass the
tests. That ensures that the Rustfmt source code adheres to our own conventions.

Talking of tests, if you add a new feature or fix a bug, please also add a test.
It's really easy, see above for details. Please run `cargo test` before
It's really easy, see above for details. Please [run the tests](#running-tests) locally before
submitting a PR to ensure your patch passes all tests, it's pretty quick.

Rustfmt is post-1.0 and within major version releases we strive for backwards
Expand Down
72 changes: 65 additions & 7 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# rustfmt [![Build Status](https://travis-ci.com/rust-lang/rustfmt.svg?branch=master)](https://travis-ci.com/rust-lang/rustfmt) [![Build Status](https://ci.appveyor.com/api/projects/status/github/rust-lang/rustfmt?svg=true)](https://ci.appveyor.com/project/rust-lang-libs/rustfmt) [![crates.io](https://img.shields.io/crates/v/rustfmt-nightly.svg)](https://crates.io/crates/rustfmt-nightly) [![Travis Configuration Status](https://img.shields.io/travis/davidalber/rustfmt-travis.svg?label=travis%20example)](https://travis-ci.org/davidalber/rustfmt-travis)
# rustfmt [![Linux badge][linux-build-status]][linux-build] [![Mac badge][mac-build-status]][mac-build] [![Windows badge][windows-build-status]][windows-build] [![crates.io badge][cratesio-badge]][cratesio-package] [![Travis config badge][travis-config-badge]][travis-config-job]

A tool for formatting Rust code according to style guidelines.

Expand Down Expand Up @@ -82,11 +82,22 @@ rustup component add rustfmt

## Installing from source

To install from source (nightly required), first checkout to the tag or branch you want to install, then issue
To install from source (nightly required), first checkout to the tag or branch for the version of rustfmt you want.

The easiest way to install is via [cargo make][cargo-make]

```sh
cargo make install
```

Alternatively, you can run `cargo install` directly as long as you set the required environment variables and features.

```sh
cargo install --path .
export CFG_RELEASE=1.45.0-nightly
export CFG_RELEASE=nightly
cargo install --path . --force --locked --features rustfmt,cargo-fmt
```
(Windows users can use `set` to specify the environment variable values)

This will install `rustfmt` in your `~/.cargo/bin`. Make sure to add `~/.cargo/bin` directory to
your PATH variable.
Expand Down Expand Up @@ -146,9 +157,42 @@ for more info.

## How to build and test

`cargo build` to build.
We recommend using [cargo make][cargo-make] when working with the rustfmt codebase.

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.

For example:
```sh
export CFG_RELEASE=1.45.0-nightly
export CFG_RELEASE=nightly
```
(Windows users can use `set` to specify the environment variable values)

To build with `cargo make`:

```sh
cargo make build
```

Or alternatively with `cargo` directly:
```sh
cargo build --all-features
# or
CFG_RELEASE_CHANNEL=nightly CFG_RELEASE=1.45.0-nightly cargo build --all-features
```

To run tests with `cargo make`:

```sh
cargo make test
```

`cargo test --manifest-path rustfmt-core/Cargo.toml` to run all tests.
Or alternatively with `cargo` directly:
```sh
cargo test --all-features
# or
CFG_RELEASE_CHANNEL=nightly CFG_RELEASE=1.45.0-nightly cargo test --all-features
```

To run rustfmt after this, use `cargo run --bin rustfmt -- filename`. See the
notes above on running rustfmt.
Expand All @@ -167,8 +211,11 @@ guide] that has been formalized through the [style RFC
process][fmt rfcs].

Configuration options are either stable or unstable. Stable options can always
be used, while unstable ones are only available on a nightly toolchain, and opt-in.
See [GitHub page](https://rust-lang.github.io/rustfmt/) for details.
be used on any channel. Unstable options are always available on nightly, but can only be used on stable and beta with an explicit opt-in (starting in Rustfmt v2.0).

Unstable options are not available on stable/beta with Rustfmt v1.x.

See the configuration documentation on the Rustfmt [GitHub page](https://rust-lang.github.io/rustfmt/) for details (look for the `unstable_features` section).

### Rust's Editions

Expand Down Expand Up @@ -231,3 +278,14 @@ See [LICENSE-APACHE](LICENSE-APACHE) and [LICENSE-MIT](LICENSE-MIT) for details.
[rust]: https://github.com/rust-lang/rust
[fmt rfcs]: https://github.com/rust-lang-nursery/fmt-rfcs
[style guide]: https://github.com/rust-lang-nursery/fmt-rfcs/blob/master/guide/guide.md
[cargo-make]: https://sagiegurari.github.io/cargo-make/
[linux-build-status]: https://img.shields.io/github/workflow/status/rust-lang/rustfmt/linux/master?label=linux&style=flat-square
[linux-build]: https://github.com/rust-lang/rustfmt/actions?query=workflow%3Alinux+branch%3Amaster
[mac-build-status]: https://img.shields.io/github/workflow/status/rust-lang/rustfmt/mac/master?label=mac&style=flat-square
[mac-build]: https://github.com/rust-lang/rustfmt/actions?query=workflow%3Amac+branch%3Amaster
[windows-build-status]: https://img.shields.io/github/workflow/status/rust-lang/rustfmt/windows/master?label=windows&style=flat-square
[windows-build]: https://github.com/rust-lang/rustfmt/actions?query=workflow%3Awindows+branch%3Amaster
[cratesio-badge]: https://img.shields.io/crates/v/rustfmt-nightly?style=flat-square
[cratesio-package]: https://crates.io/crates/rustfmt-nightly
[travis-config-badge]: https://img.shields.io/travis/davidalber/rustfmt-travis?label=travis%20example&style=flat-square
[travis-config-job]: https://travis-ci.org/davidalber/rustfmt-travis