From 5a14f3791db8b87a5e292a72dc1086cb0e72e93b Mon Sep 17 00:00:00 2001 From: Manish Goregaokar Date: Mon, 4 Jan 2016 09:31:29 +0530 Subject: [PATCH 1/8] Improve syntax-index entry for lifetime bounds --- src/doc/book/syntax-index.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/doc/book/syntax-index.md b/src/doc/book/syntax-index.md index f7e32943c63..8116247c766 100644 --- a/src/doc/book/syntax-index.md +++ b/src/doc/book/syntax-index.md @@ -132,7 +132,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)]. From dc6ed63655b6698828b363e49d6bd9df76633334 Mon Sep 17 00:00:00 2001 From: Greg Chapple Date: Mon, 25 Jan 2016 14:07:10 +0000 Subject: [PATCH 2/8] Added info on the build system to contributing guide I recently wrote a blog post on contributing to the Rust compiler which gained some interest. It was mentioned in a comment on Reddit that it would be useful to integrate some of the information from that post to the official contributing guide. This is the start of my efforts to integrate what I wrote with the official guide. This commit adds information on the build system. It is not a complete guide on the build system, but it should be enough to provide a good starting place for those wishing to contribute. --- CONTRIBUTING.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e864172e813..94576bbac1f 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,60 @@ to do this is to invoke `rustc` like this: $ RUST_BACKTRACE=1 rustc ... ``` +## The Build System + +The build system for Rust is complex. It covers bootstrapping the compiler, +running tests, building documentation and more. Unless you are familiar with +Makefiles, I wouldn't suggest trying to understand everything going on in +Rust's setup - there's a lot there, and you can get lost trying to understand +it all. + +If Makefiles are your thing, though, all the configuration lives in +[the `mk` directory][mkdir] in the project root. + +[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) +- `--disable-valgrind-rpass` - Don't run tests with valgrind +- `--enable-clang` - Prefer clang to gcc for building dependencies (ie LLVM) +- `--enable-ccache` - Invoke clang/gcc with ccache to re-use object files between builds + +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. + ## Pull Requests Pull requests are the primary mechanism we use to change Rust. GitHub itself From 6fd728db6d062a18887b4a0ee5af9aa6215593ce Mon Sep 17 00:00:00 2001 From: Greg Chapple Date: Tue, 26 Jan 2016 14:14:09 +0000 Subject: [PATCH 3/8] Updated to reflect comments from review - Tweaked the build system intro paragraph - Added some more configure options & explanations - Added additional make target --- CONTRIBUTING.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 94576bbac1f..e3d5fb83e37 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -81,13 +81,13 @@ $ RUST_BACKTRACE=1 rustc ... ## The Build System The build system for Rust is complex. It covers bootstrapping the compiler, -running tests, building documentation and more. Unless you are familiar with -Makefiles, I wouldn't suggest trying to understand everything going on in -Rust's setup - there's a lot there, and you can get lost trying to understand -it all. +running tests, building documentation and more. -If Makefiles are your thing, though, all the configuration lives in -[the `mk` directory][mkdir] in the project root. +If Makefiles are your thing, all the configuration lives in +[the `mk` directory][mkdir] in the project root. Is 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/ @@ -106,9 +106,12 @@ 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 (ie LLVM) +- `--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`. @@ -131,6 +134,7 @@ Some common make targets are: 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 From 05f7b59352abe51f4b1b4897dfcdae7feb33a3a3 Mon Sep 17 00:00:00 2001 From: Greg Chapple Date: Tue, 26 Jan 2016 14:41:29 +0000 Subject: [PATCH 4/8] Re-worded intro paragraph to be more positive --- CONTRIBUTING.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e3d5fb83e37..e4870aa6a89 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -80,14 +80,16 @@ $ RUST_BACKTRACE=1 rustc ... ## The Build System -The build system for Rust is complex. It covers bootstrapping the compiler, -running tests, building documentation and more. +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. -If Makefiles are your thing, all the configuration lives in -[the `mk` directory][mkdir] in the project root. Is 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]. +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/ From e23f8b095b341b43a9696562889a4db096bebb9d Mon Sep 17 00:00:00 2001 From: Matt Brubeck Date: Tue, 26 Jan 2016 09:49:26 -0800 Subject: [PATCH 5/8] Fix examples that use missing_docs lint The missing_docs lint only applies to public items in public modules, so this example code did not actually generate any warnings or errors. --- src/doc/reference.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/doc/reference.md b/src/doc/reference.md index f0fdae27ac7..46fdee2bb5a 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. From 638555e64d0fc66adc30bc57add2fe6f9164483c Mon Sep 17 00:00:00 2001 From: Alex Burka Date: Tue, 26 Jan 2016 13:43:43 -0500 Subject: [PATCH 6/8] book: cover UFCS in Syntax Index --- src/doc/book/syntax-index.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/src/doc/book/syntax-index.md b/src/doc/book/syntax-index.md index f7e32943c63..c2891704352 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 part of UFCS. See [Casting Between Types (`as`)], [Universal Function Call Syntax (Angle-bracket Form)]. * `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)]. @@ -117,6 +117,9 @@ * `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]. * `::…`: 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)]. @@ -234,6 +237,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 From 2f633b2204a16b5f21326c9f8d676b10862f1254 Mon Sep 17 00:00:00 2001 From: Alex Burka Date: Tue, 26 Jan 2016 14:36:48 -0500 Subject: [PATCH 7/8] capitalization and associated types --- src/doc/book/syntax-index.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/doc/book/syntax-index.md b/src/doc/book/syntax-index.md index c2891704352..3fa587ba085 100644 --- a/src/doc/book/syntax-index.md +++ b/src/doc/book/syntax-index.md @@ -2,7 +2,7 @@ ## Keywords -* `as`: primitive casting, or part of UFCS. See [Casting Between Types (`as`)], [Universal Function Call Syntax (Angle-bracket Form)]. +* `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,11 +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)]. +* `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)]. From 5c61be68d03ebce1912a625661c6fa3cc150b106 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Tue, 26 Jan 2016 17:47:01 -0500 Subject: [PATCH 8/8] Mention that globs import public symbols Fixes #30954 --- src/doc/book/crates-and-modules.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/src/doc/book/crates-and-modules.md b/src/doc/book/crates-and-modules.md index 849c5f1212a..0c9ed0bf122 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