diff --git a/Contributing.md b/Contributing.md index d25e5256bdd..98452015598 100644 --- a/Contributing.md +++ b/Contributing.md @@ -14,16 +14,38 @@ 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 @@ -31,23 +53,38 @@ 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 @@ -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. @@ -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. @@ -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 diff --git a/README.md b/README.md index 3b4511157c4..35329c23734 100644 --- a/README.md +++ b/README.md @@ -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. @@ -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. @@ -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. @@ -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 @@ -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