X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;f=README.md;h=c9153a6eade4d769c594eadfe12dccd12cb3b4fd;hb=825207dd2ed2fcf1f9eb439f72fa5fae1e88847b;hp=597e9fb889bf379c69697235c6b0d8eb1dac2be5;hpb=e133fc5106429de4f48272f14be72e24bd1b3236;p=rust.git diff --git a/README.md b/README.md index 597e9fb889b..c9153a6eade 100644 --- a/README.md +++ b/README.md @@ -6,28 +6,14 @@ If you'd like to help out (and you should, it's a fun project!), see [Contributing.md](Contributing.md) and our [Code of Conduct](CODE_OF_CONDUCT.md). -We are changing the default style used by rustfmt. There is an ongoing [RFC -process][fmt rfcs]. The last version using the old style was 0.8.6. From 0.9 -onwards, the RFC style is the default. If you want the old style back, you can -use [legacy-rustfmt.toml](legacy-rustfmt.toml) as your rustfmt.toml. - -The current `master` branch uses libsyntax (part of the compiler). It is -published as `rustfmt-nightly`. The `syntex` branch uses Syntex instead of -libsyntax, it is published (for now) as `rustfmt`. Most development happens on -the `master` branch, however, this only supports nightly toolchains. If you use -stable or beta Rust toolchains, you must use the Syntex version (which is likely -to be a bit out of date). Version 0.1 of rustfmt-nightly is forked from version -0.9 of the syntex branch. - You can use rustfmt in Travis CI builds. We provide a minimal Travis CI configuration (see [here](#checking-style-on-a-ci-server)) and verify its status using another repository. The status of that repository's build is reported by the "travis example" badge above. - ## Quick start -You can use `rustfmt` on Rust 1.24 and above. +You can run `rustfmt` with Rust 1.24 and above. To install: @@ -50,6 +36,12 @@ To run: cargo +nightly fmt ``` +To format code that requires edition 2018, create a `rustfmt.toml` [configuration](#configuring-rustfmt) file containing: + +```toml +edition = "2018" +``` + ## Limitations Rustfmt tries to work on as much Rust code as possible, sometimes, the code @@ -88,6 +80,7 @@ rustup component add rustfmt-preview ## Installing from source To install from source (nightly required), first checkout to the tag or branch you want to install, then issue + ``` cargo install --path . ``` @@ -123,19 +116,19 @@ completed without error (whether or not changes were made). * [Atom](atom.md) * Visual Studio Code using [vscode-rust](https://github.com/editor-rs/vscode-rust), [vsc-rustfmt](https://github.com/Connorcpu/vsc-rustfmt) or [rls_vscode](https://github.com/jonathandturner/rls_vscode) through RLS. + ## Checking style on a CI server To keep your code base consistently formatted, it can be helpful to fail the CI build when a pull request contains unformatted code. Using `--check` instructs rustfmt to exit with an error code if the input is not formatted correctly. -It will also print any found differences. +It will also print any found differences. (Older versions of Rustfmt don't +support `--check`, use `--write-mode diff`). A minimal Travis setup could look like this (requires Rust 1.24.0 or greater): ```yaml language: rust -rust: -- nightly before_script: - rustup component add rustfmt-preview script: @@ -144,6 +137,9 @@ script: - cargo test ``` +See [this blog post](https://medium.com/@ag_dubs/enforcing-style-in-ci-for-rust-projects-18f6b09ec69d) +for more info. + ## How to build and test `cargo build` to build. @@ -159,7 +155,7 @@ notes above on running rustfmt. Rustfmt is designed to be very configurable. You can create a TOML file called `rustfmt.toml` or `.rustfmt.toml`, place it in the project or any other parent directory and it will apply the options in that file. See `rustfmt ---config-help` for the options which are available, or if you prefer to see +--help=config` for the options which are available, or if you prefer to see visual style previews, [Configurations.md](Configurations.md). By default, Rustfmt uses a style which conforms to the [Rust style guide][style @@ -182,41 +178,18 @@ See [Configurations.md](Configurations.md) for details. * When you run rustfmt, place a file named `rustfmt.toml` or `.rustfmt.toml` in target file directory or its parents to override the default settings of rustfmt. You can generate a file containing the default configuration with - `rustfmt --dump-default-config rustfmt.toml` and customize as needed. + `rustfmt --print-config default rustfmt.toml` and customize as needed. * After successful compilation, a `rustfmt` executable can be found in the target directory. * If you're having issues compiling Rustfmt (or compile errors when trying to install), make sure you have the most recent version of Rust installed. -* If you get an error like `error while loading shared libraries` while starting - up rustfmt you should try the following: - - On Linux: - - ``` - export LD_LIBRARY_PATH=$(rustc --print sysroot)/lib:$LD_LIBRARY_PATH - ``` - - On MacOS: - - ``` - export DYLD_LIBRARY_PATH=$(rustc --print sysroot)/lib:$DYLD_LIBRARY_PATH - ``` - - On Windows (Git Bash/Mingw): - - ``` - export PATH=$(rustc --print sysroot)/lib/rustlib/x86_64-pc-windows-gnu/lib/:$PATH - ``` - - (Substitute `x86_64` by `i686` and `gnu` by `msvc` depending on which version of rustc was used to install rustfmt). - * You can change the way rustfmt emits the changes with the --emit flag: Example: ``` - cargo fmt --emit files + cargo fmt -- --emit files ``` Options: @@ -224,7 +197,7 @@ See [Configurations.md](Configurations.md) for details. | Flag |Description| Nightly Only | |:---:|:---:|:---:| | files | overwrites output to files | No | - | stdout | writes output to stdout | No | + | stdout | writes output to stdout | No | | coverage | displays how much of the input file was processed | Yes | | checkstyle | emits in a checkstyle format | Yes |