diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e864172e81332..e4870aa6a8980 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,6 +6,7 @@ links to the major sections: * [Feature Requests](#feature-requests) * [Bug Reports](#bug-reports) +* [The Build System](#the-build-system) * [Pull Requests](#pull-requests) * [Writing Documentation](#writing-documentation) * [Issue Triage](#issue-triage) @@ -77,6 +78,66 @@ to do this is to invoke `rustc` like this: $ RUST_BACKTRACE=1 rustc ... ``` +## The Build System + +Rust's build system allows you to bootstrap the compiler, run tests & +benchmarks, generate documentation, install a fresh build of Rust, and more. +It's your best friend when working on Rust, allowing you to compile & test +your contributions before submission. + +All the configuration for the build system lives in [the `mk` directory][mkdir] +in the project root. It can be hard to follow in places, as it uses some +advanced Make features which make for some challenging reading. If you have +questions on the build system internals, try asking in +[`#rust-internals`][pound-rust-internals]. + +[mkdir]: https://github.com/rust-lang/rust/tree/master/mk/ + +### Configuration + +Before you can start building the compiler you need to configure the build for +your system. In most cases, that will just mean using the defaults provided +for Rust. Configuring involves invoking the `configure` script in the project +root. + +``` +./configure +``` + +There are large number of options accepted by this script to alter the +configuration used later in the build process. Some options to note: + +- `--enable-debug` - Build a debug version of the compiler (disables optimizations) +- `--enable-optimize` - Enable optimizations (can be used with `--enable-debug` + to make a debug build with optimizations) +- `--disable-valgrind-rpass` - Don't run tests with valgrind +- `--enable-clang` - Prefer clang to gcc for building dependencies (e.g., LLVM) +- `--enable-ccache` - Invoke clang/gcc with ccache to re-use object files between builds +- `--enable-compiler-docs` - Build compiler documentation + +To see a full list of options, run `./configure --help`. + +### Useful Targets + +Some common make targets are: + +- `make rustc-stage1` - build up to (and including) the first stage. For most + cases we don't need to build the stage2 compiler, so we can save time by not + building it. The stage1 compiler is a fully functioning compiler and + (probably) will be enough to determine if your change works as expected. +- `make check` - build the full compiler & run all tests (takes a while). This + is what gets run by the continuous integration system against your pull + request. You should run this before submitting to make sure your tests pass + & everything builds in the correct manner. +- `make check-stage1-std NO_REBUILD=1` - test the standard library without + rebuilding the entire compiler +- `make check TESTNAME=.rs` - Run a single test file +- `make check-stage1-rpass TESTNAME=.rs` - Run a single + rpass test with the stage1 compiler (this will be quicker than running the + command above as we only build the stage1 compiler, not the entire thing). + You can also leave off the `-rpass` to run all stage1 test types. +- `make check-stage1-coretest` - Run stage1 tests in `libcore`. + ## Pull Requests Pull requests are the primary mechanism we use to change Rust. GitHub itself diff --git a/src/doc/book/crates-and-modules.md b/src/doc/book/crates-and-modules.md index 849c5f1212a57..0c9ed0bf12281 100644 --- a/src/doc/book/crates-and-modules.md +++ b/src/doc/book/crates-and-modules.md @@ -567,10 +567,11 @@ to it as "sayings". Similarly, the first `use` statement pulls in the `ja_greetings` as opposed to simply `greetings`. This can help to avoid ambiguity when importing similarly-named items from different places. -The second `use` statement uses a star glob to bring in _all_ symbols from the -`sayings::japanese::farewells` module. As you can see we can later refer to +The second `use` statement uses a star glob to bring in all public symbols from +the `sayings::japanese::farewells` module. As you can see we can later refer to the Japanese `goodbye` function with no module qualifiers. This kind of glob -should be used sparingly. +should be used sparingly. It’s worth noting that it only imports the public +symbols, even if the code doing the globbing is in the same module. The third `use` statement bears more explanation. It's using "brace expansion" globbing to compress three `use` statements into one (this sort of syntax diff --git a/src/doc/book/syntax-index.md b/src/doc/book/syntax-index.md index f7e32943c638e..6782bdb4985ec 100644 --- a/src/doc/book/syntax-index.md +++ b/src/doc/book/syntax-index.md @@ -2,7 +2,7 @@ ## Keywords -* `as`: primitive casting. See [Casting Between Types (`as`)]. +* `as`: primitive casting, or disambiguating the specific trait containing an item. See [Casting Between Types (`as`)], [Universal Function Call Syntax (Angle-bracket Form)], [Associated Types]. * `break`: break out of loop. See [Loops (Ending Iteration Early)]. * `const`: constant items and constant raw pointers. See [`const` and `static`], [Raw Pointers]. * `continue`: continue to next loop iteration. See [Loops (Ending Iteration Early)]. @@ -115,8 +115,11 @@ * `::path`: path relative to the crate root (*i.e.* an explicitly absolute path). See [Crates and Modules (Re-exporting with `pub use`)]. * `self::path`: path relative to the current module (*i.e.* an explicitly relative path). See [Crates and Modules (Re-exporting with `pub use`)]. * `super::path`: path relative to the parent of the current module. See [Crates and Modules (Re-exporting with `pub use`)]. -* `type::ident`: associated constants, functions, and types. See [Associated Types]. +* `type::ident`, `::ident`: associated constants, functions, and types. See [Associated Types]. * `::…`: associated item for a type which cannot be directly named (*e.g.* `<&T>::…`, `<[T]>::…`, *etc.*). See [Associated Types]. +* `trait::method(…)`: disambiguating a method call by naming the trait which defines it. See [Universal Function Call Syntax]. +* `type::method(…)`: disambiguating a method call by naming the type for which it's defined. See [Universal Function Call Syntax]. +* `::method(…)`: disambiguating a method call by naming the trait _and_ type. See [Universal Function Call Syntax (Angle-bracket Form)]. @@ -132,7 +135,8 @@ * `T: U`: generic parameter `T` constrained to types that implement `U`. See [Traits]. -* `T: 'a`: generic type `T` must outlive lifetime `'a`. +* `T: 'a`: generic type `T` must outlive lifetime `'a`. When we say that a type 'outlives' the lifetime, we mean that it cannot transitively contain any references with lifetimes shorter than `'a`. +* `T : 'static`: The generic type `T` contains no borrowed references other than `'static` ones. * `'b: 'a`: generic lifetime `'b` must outlive lifetime `'a`. * `T: ?Sized`: allow generic type parameter to be a dynamically-sized type. See [Unsized Types (`?Sized`)]. * `'a + trait`, `trait + trait`: compound type constraint. See [Traits (Multiple Trait Bounds)]. @@ -234,6 +238,8 @@ [Traits (`where` clause)]: traits.html#where-clause [Traits (Multiple Trait Bounds)]: traits.html#multiple-trait-bounds [Traits]: traits.html +[Universal Function Call Syntax]: ufcs.html +[Universal Function Call Syntax (Angle-bracket Form)]: ufcs.html#angle-bracket-form [Unsafe]: unsafe.html [Unsized Types (`?Sized`)]: unsized-types.html#sized [Variable Bindings]: variable-bindings.html diff --git a/src/doc/reference.md b/src/doc/reference.md index f0fdae27ac7fb..46fdee2bb5a9e 100644 --- a/src/doc/reference.md +++ b/src/doc/reference.md @@ -2095,7 +2095,7 @@ along with their default settings. [Compiler plugins](book/compiler-plugins.html#lint-plugins) can provide additional lint checks. ```{.ignore} -mod m1 { +pub mod m1 { // Missing documentation is ignored here #[allow(missing_docs)] pub fn undocumented_one() -> i32 { 1 } @@ -2115,9 +2115,9 @@ check on and off: ```{.ignore} #[warn(missing_docs)] -mod m2{ +pub mod m2{ #[allow(missing_docs)] - mod nested { + pub mod nested { // Missing documentation is ignored here pub fn undocumented_one() -> i32 { 1 } @@ -2137,7 +2137,7 @@ that lint check: ```{.ignore} #[forbid(missing_docs)] -mod m3 { +pub mod m3 { // Attempting to toggle warning signals an error here #[allow(missing_docs)] /// Returns 2.