Merge ref 'd087f112b7d1:/library/compiler-builtins' from https://github.com/rust-lang/rust
Pull recent changes from rust-lang/rust via Josh. Upstream ref: d087f112b7d1323446c7b39a8b616aee7fa56b3d Filtered ref: 2d43ce8ac022170e5383f7e5a188b55564b6566a
This commit is contained in:
Trevor Gross
commit
c1db8509ec
|
|
@ -1 +1 @@
|
|||
99e7c15e81385b38a8186b51edc4577d5d7b5bdd
|
||||
14346303d760027e53214e705109a62c0f00b214
|
||||
|
|
|
|||
|
|
@ -63,10 +63,8 @@
|
|||
- [Notification groups](notification-groups/about.md)
|
||||
- [Apple](notification-groups/apple.md)
|
||||
- [ARM](notification-groups/arm.md)
|
||||
- [Cleanup Crew](notification-groups/cleanup-crew.md)
|
||||
- [Emscripten](notification-groups/emscripten.md)
|
||||
- [Fuchsia](notification-groups/fuchsia.md)
|
||||
- [LLVM](notification-groups/llvm.md)
|
||||
- [RISC-V](notification-groups/risc-v.md)
|
||||
- [Rust for Linux](notification-groups/rust-for-linux.md)
|
||||
- [WASI](notification-groups/wasi.md)
|
||||
|
|
@ -101,6 +99,8 @@
|
|||
- [Rustdoc internals](./rustdoc-internals.md)
|
||||
- [Search](./rustdoc-internals/search.md)
|
||||
- [The `rustdoc` test suite](./rustdoc-internals/rustdoc-test-suite.md)
|
||||
- [The `rustdoc-gui` test suite](./rustdoc-internals/rustdoc-gui-test-suite.md)
|
||||
- [The `rustdoc-json` test suite](./rustdoc-internals/rustdoc-json-test-suite.md)
|
||||
- [Autodiff internals](./autodiff/internals.md)
|
||||
- [Installation](./autodiff/installation.md)
|
||||
- [How to debug](./autodiff/debugging.md)
|
||||
|
|
|
|||
|
|
@ -16,7 +16,9 @@ LooseTypes // Risk incorrect derivatives instead of aborting when missing Type I
|
|||
```
|
||||
|
||||
<div class="warning">
|
||||
|
||||
`LooseTypes` is often helpful to get rid of Enzyme errors stating `Can not deduce type of <X>` and to be able to run some code. But please keep in mind that this flag absolutely has the chance to cause incorrect gradients. Even worse, the gradients might be correct for certain input values, but not for others. So please create issues about such bugs and only use this flag temporarily while you wait for your bug to be fixed.
|
||||
|
||||
</div>
|
||||
|
||||
### Benchmark flags
|
||||
|
|
|
|||
|
|
@ -55,7 +55,7 @@ Bootstrap will conditionally build `tracing` support and enable `tracing` output
|
|||
|
||||
Example basic usage[^just-trace]:
|
||||
|
||||
[^just-trace]: It is not recommend to use *just* `BOOTSTRAP_TRACING=TRACE` because that will dump *everything* at `TRACE` level, including logs intentionally gated behind custom targets as they are too verbose even for `TRACE` level by default.
|
||||
[^just-trace]: It is not recommended to use *just* `BOOTSTRAP_TRACING=TRACE` because that will dump *everything* at `TRACE` level, including logs intentionally gated behind custom targets as they are too verbose even for `TRACE` level by default.
|
||||
|
||||
```bash
|
||||
$ BOOTSTRAP_TRACING=bootstrap=TRACE ./x build library --stage 1
|
||||
|
|
|
|||
|
|
@ -59,6 +59,14 @@ always overrides the inner ones.
|
|||
|
||||
## Configuring `rust-analyzer` for `rustc`
|
||||
|
||||
### Checking the "library" tree
|
||||
|
||||
Checking the "library" tree requires a stage1 compiler, which can be a heavy process on some computers.
|
||||
For this reason, bootstrap has a flag called `--skip-std-check-if-no-download-rustc` that skips checking the
|
||||
"library" tree if `rust.download-rustc` isn't available. If you want to avoid putting a heavy load on your computer
|
||||
with `rust-analyzer`, you can add the `--skip-std-check-if-no-download-rustc` flag to your `./x check` command in
|
||||
the `rust-analyzer` configuration.
|
||||
|
||||
### Project-local rust-analyzer setup
|
||||
|
||||
`rust-analyzer` can help you check and format your code whenever you save a
|
||||
|
|
|
|||
|
|
@ -1,6 +1,10 @@
|
|||
# Async closures/"coroutine-closures"
|
||||
|
||||
<!-- toc -->
|
||||
|
||||
Please read [RFC 3668](https://rust-lang.github.io/rfcs/3668-async-closures.html) to understand the general motivation of the feature. This is a very technical and somewhat "vertical" chapter; ideally we'd split this and sprinkle it across all the relevant chapters, but for the purposes of understanding async closures *holistically*, I've put this together all here in one chapter.
|
||||
|
||||
# Coroutine-closures -- a technical deep dive
|
||||
## Coroutine-closures -- a technical deep dive
|
||||
|
||||
Coroutine-closures are a generalization of async closures, being special syntax for closure expressions which return a coroutine, notably one that is allowed to capture from the closure's upvars.
|
||||
|
||||
|
|
@ -8,9 +12,11 @@ For now, the only usable kind of coroutine-closure is the async closure, and sup
|
|||
|
||||
As a consequence of the code being somewhat general, this document may flip between calling them "async closures" and "coroutine-closures". The future that is returned by the async closure will generally be called the "coroutine" or the "child coroutine".
|
||||
|
||||
## HIR
|
||||
### HIR
|
||||
|
||||
Async closures (and in the future, other coroutine flavors such as `gen`) are represented in HIR as a `hir::Closure` whose closure-kind is `ClosureKind::CoroutineClosure(_)`[^k1], which wraps an async block, which is also represented in HIR as a `hir::Closure`) and whose closure-kind is `ClosureKind::Closure(CoroutineKind::Desugared(_, CoroutineSource::Closure))`[^k2].
|
||||
Async closures (and in the future, other coroutine flavors such as `gen`) are represented in HIR as a `hir::Closure`.
|
||||
The closure-kind of the `hir::Closure` is `ClosureKind::CoroutineClosure(_)`[^k1], which wraps an async block, which is also represented in HIR as a `hir::Closure`.
|
||||
The closure-kind of the async block is `ClosureKind::Closure(CoroutineKind::Desugared(_, CoroutineSource::Closure))`[^k2].
|
||||
|
||||
[^k1]: <https://github.com/rust-lang/rust/blob/5ca0e9fa9b2f92b463a0a2b0b34315e09c0b7236/compiler/rustc_ast_lowering/src/expr.rs#L1147>
|
||||
|
||||
|
|
@ -24,7 +30,7 @@ Like `async fn`, when lowering an async closure's body, we need to unconditional
|
|||
|
||||
[^l3]: <https://github.com/rust-lang/rust/blob/5ca0e9fa9b2f92b463a0a2b0b34315e09c0b7236/compiler/rustc_hir_typeck/src/upvar.rs#L250-L256>
|
||||
|
||||
## `rustc_middle::ty` Representation
|
||||
### `rustc_middle::ty` Representation
|
||||
|
||||
For the purposes of keeping the implementation mostly future-compatible (i.e. with gen `|| {}` and `async gen || {}`), most of this section calls async closures "coroutine-closures".
|
||||
|
||||
|
|
@ -72,7 +78,7 @@ To most easily construct the `Coroutine` that a coroutine-closure returns, you c
|
|||
|
||||
Most of the args to that function will be components that you can get out of the `CoroutineArgs`, except for the `goal_kind: ClosureKind` which controls which flavor of coroutine to return based off of the `ClosureKind` passed in -- i.e. it will prepare the by-ref coroutine if `ClosureKind::Fn | ClosureKind::FnMut`, and the by-move coroutine if `ClosureKind::FnOnce`.
|
||||
|
||||
## Trait Hierarchy
|
||||
### Trait Hierarchy
|
||||
|
||||
We introduce a parallel hierarchy of `Fn*` traits that are implemented for . The motivation for the introduction was covered in a blog post: [Async Closures](https://hackmd.io/@compiler-errors/async-closures).
|
||||
|
||||
|
|
@ -98,11 +104,11 @@ We mention above that "regular" callable types can implement `AsyncFn*`, but the
|
|||
|
||||
See the "follow-up: when do..." section below for an elaborated answer. The full answer describes a pretty interesting and hopefully thorough heuristic that is used to ensure that most async closures "just work".
|
||||
|
||||
## Tale of two bodies...
|
||||
### Tale of two bodies...
|
||||
|
||||
When async closures are called with `AsyncFn`/`AsyncFnMut`, they return a coroutine that borrows from the closure. However, when they are called via `AsyncFnOnce`, we consume that closure, and cannot return a coroutine that borrows from data that is now dropped.
|
||||
|
||||
To work around around this limitation, we synthesize a separate by-move MIR body for calling `AsyncFnOnce::call_once` on a coroutine-closure that can be called by-ref.
|
||||
To work around this limitation, we synthesize a separate by-move MIR body for calling `AsyncFnOnce::call_once` on a coroutine-closure that can be called by-ref.
|
||||
|
||||
This body operates identically to the "normal" coroutine returned from calling the coroutine-closure, except for the fact that it has a different set of upvars, since we must *move* the captures from the parent coroutine-closure into the child coroutine.
|
||||
|
||||
|
|
@ -120,7 +126,7 @@ Since we've synthesized a new def id, this query is also responsible for feeding
|
|||
|
||||
[^b3]: <https://github.com/rust-lang/rust/blob/5ca0e9fa9b2f92b463a0a2b0b34315e09c0b7236/compiler/rustc_mir_transform/src/lib.rs#L339-L342>
|
||||
|
||||
## Closure signature inference
|
||||
### Closure signature inference
|
||||
|
||||
The closure signature inference algorithm for async closures is a bit more complicated than the inference algorithm for "traditional" closures. Like closures, we iterate through all of the clauses that may be relevant (for the expectation type passed in)[^deduce1].
|
||||
|
||||
|
|
@ -173,7 +179,7 @@ s.as_bytes();
|
|||
|
||||
So *instead*, we use this alias (in this case, a projection: `AsyncFnKindHelper::Upvars<'env, ...>`) to delay the computation of the *tupled upvars* and give us something to put in its place, while still allowing us to return a `TyKind::Coroutine` (which is a rigid type) and we may successfully confirm the built-in traits we need (in our case, `Future`), since the `Future` implementation doesn't depend on the upvars at all.
|
||||
|
||||
## Upvar analysis
|
||||
### Upvar analysis
|
||||
|
||||
By and large, the upvar analysis for coroutine-closures and their child coroutines proceeds like normal upvar analysis. However, there are several interesting bits that happen to account for async closures' special natures:
|
||||
|
||||
|
|
@ -262,7 +268,7 @@ let c = async || {
|
|||
|
||||
If either of these cases apply, then we should capture the borrow with the lifetime of the parent coroutine-closure's env. Luckily, if this function is not correct, then the program is not unsound, since we still borrowck and validate the choices made from this function -- the only side-effect is that the user may receive unnecessary borrowck errors.
|
||||
|
||||
## Instance resolution
|
||||
### Instance resolution
|
||||
|
||||
If a coroutine-closure has a closure-kind of `FnOnce`, then its `AsyncFnOnce::call_once` and `FnOnce::call_once` implementations resolve to the coroutine-closure's body[^res1], and the `Future::poll` of the coroutine that gets returned resolves to the body of the child closure.
|
||||
|
||||
|
|
@ -282,7 +288,7 @@ This is represented by the `ConstructCoroutineInClosureShim`[^i1]. The `receiver
|
|||
|
||||
[^i3]: <https://github.com/rust-lang/rust/blob/07cbbdd69363da97075650e9be24b78af0bcdd23/compiler/rustc_middle/src/ty/instance.rs#L841>
|
||||
|
||||
## Borrow-checking
|
||||
### Borrow-checking
|
||||
|
||||
It turns out that borrow-checking async closures is pretty straightforward. After adding a new `DefiningTy::CoroutineClosure`[^bck1] variant, and teaching borrowck how to generate the signature of the coroutine-closure[^bck2], borrowck proceeds totally fine.
|
||||
|
||||
|
|
|
|||
|
|
@ -158,9 +158,6 @@ feel comfortable jumping straight into the large `rust-lang/rust` codebase.
|
|||
The following tasks are doable without much background knowledge but are
|
||||
incredibly helpful:
|
||||
|
||||
- [Cleanup crew][iceb]: find minimal reproductions of ICEs, bisect
|
||||
regressions, etc. This is a way of helping that saves a ton of time for
|
||||
others to fix an error later.
|
||||
- [Writing documentation][wd]: if you are feeling a bit more intrepid, you could try
|
||||
to read a part of the code and write doc comments for it. This will help you
|
||||
to learn some part of the compiler while also producing a useful artifact!
|
||||
|
|
@ -179,7 +176,6 @@ incredibly helpful:
|
|||
[users]: https://users.rust-lang.org/
|
||||
[so]: http://stackoverflow.com/questions/tagged/rust
|
||||
[community-library]: https://github.com/rust-lang/rfcs/labels/A-community-library
|
||||
[iceb]: ./notification-groups/cleanup-crew.md
|
||||
[wd]: ./contributing.md#writing-documentation
|
||||
[wg]: https://rust-lang.github.io/compiler-team/working-groups/
|
||||
[triage]: ./contributing.md#issue-triage
|
||||
|
|
|
|||
|
|
@ -142,7 +142,8 @@ The most common cause is that you rebased after a change and ran `git add .` wit
|
|||
`x` to update the submodules. Alternatively, you might have run `cargo fmt` instead of `x fmt`
|
||||
and modified files in a submodule, then committed the changes.
|
||||
|
||||
To fix it, do the following things:
|
||||
To fix it, do the following things (if you changed a submodule other than cargo,
|
||||
replace `src/tools/cargo` with the path to that submodule):
|
||||
|
||||
1. See which commit has the accidental changes: `git log --stat -n1 src/tools/cargo`
|
||||
2. Revert the changes to that commit: `git checkout <my-commit>~ src/tools/cargo`. Type `~`
|
||||
|
|
|
|||
|
|
@ -265,13 +265,13 @@ Another problem was that it was not possible to normalize `ParamEnv`s correctly
|
|||
|
||||
Given a type such as `for<'a> fn(<?x as Trait<'a>::Assoc>)`, it is not possible to correctly handle this with the old solver's approach to normalization.
|
||||
|
||||
If we were to normalize it to `for<'a> fn(?y)` and register a goal to normalize `for<'a> <?x as Trait<'a>>::Assoc -> ?y`, this would result in errors in cases where `<?x as Trait<'a>>::Assoc` normalized to `&'a u32`. The inference variable `?y` would be in a lower [universe][universes] than the placeholders made when instantiating the `for<'a>` binder.
|
||||
If we were to normalize it to `for<'a> fn(?y)` and register a goal to normalize `for<'a> <?x as Trait<'a>>::Assoc -> ?y`, this would result in errors in cases where `<?x as Trait<'a>>::Assoc` normalized to `&'a u32`. The inference variable `?y` would be in a lower [universe] than the placeholders made when instantiating the `for<'a>` binder.
|
||||
|
||||
Leaving the alias unnormalized would also be wrong as the old solver expects all aliases to be rigid. This was a soundness bug before the new solver was stabilized in coherence: [relating projection substs is unsound during coherence](https://github.com/rust-lang/rust/issues/102048).
|
||||
|
||||
Ultimately this means that it is not always possible to ensure all aliases inside of a value are rigid.
|
||||
|
||||
[universes]: https://rustc-dev-guide.rust-lang.org/borrow_check/region_inference/placeholders_and_universes.html#what-is-a-universe
|
||||
[universe]: borrow_check/region_inference/placeholders_and_universes.md#what-is-a-universe
|
||||
[deeply_normalize]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_trait_selection/traits/normalize/trait.NormalizeExt.html#tymethod.deeply_normalize
|
||||
|
||||
## Handling uses of diverging aliases
|
||||
|
|
|
|||
|
|
@ -21,9 +21,7 @@ search for existing issues that haven't been claimed yet.
|
|||
Here's the list of the notification groups:
|
||||
- [Apple](./apple.md)
|
||||
- [ARM](./arm.md)
|
||||
- [Cleanup Crew](./cleanup-crew.md)
|
||||
- [Emscripten](./emscripten.md)
|
||||
- [LLVM Icebreakers](./llvm.md)
|
||||
- [RISC-V](./risc-v.md)
|
||||
- [WASI](./wasi.md)
|
||||
- [WebAssembly](./wasm.md)
|
||||
|
|
@ -64,9 +62,7 @@ Example PRs:
|
|||
|
||||
* [Example of adding yourself to the Apple group.](https://github.com/rust-lang/team/pull/1434)
|
||||
* [Example of adding yourself to the ARM group.](https://github.com/rust-lang/team/pull/358)
|
||||
* [Example of adding yourself to the Cleanup Crew.](https://github.com/rust-lang/team/pull/221)
|
||||
* [Example of adding yourself to the Emscripten group.](https://github.com/rust-lang/team/pull/1579)
|
||||
* [Example of adding yourself to the LLVM group.](https://github.com/rust-lang/team/pull/140)
|
||||
* [Example of adding yourself to the RISC-V group.](https://github.com/rust-lang/team/pull/394)
|
||||
* [Example of adding yourself to the WASI group.](https://github.com/rust-lang/team/pull/1580)
|
||||
* [Example of adding yourself to the WebAssembly group.](https://github.com/rust-lang/team/pull/1581)
|
||||
|
|
@ -81,9 +77,7 @@ group. For example:
|
|||
```text
|
||||
@rustbot ping apple
|
||||
@rustbot ping arm
|
||||
@rustbot ping cleanup-crew
|
||||
@rustbot ping emscripten
|
||||
@rustbot ping icebreakers-llvm
|
||||
@rustbot ping risc-v
|
||||
@rustbot ping wasi
|
||||
@rustbot ping wasm
|
||||
|
|
@ -92,12 +86,12 @@ group. For example:
|
|||
|
||||
To make some commands shorter and easier to remember, there are aliases,
|
||||
defined in the [`triagebot.toml`] file. For example, all of these commands
|
||||
are equivalent and will ping the Cleanup Crew:
|
||||
are equivalent and will ping the Apple group:
|
||||
|
||||
```text
|
||||
@rustbot ping cleanup
|
||||
@rustbot ping bisect
|
||||
@rustbot ping reduce
|
||||
@rustbot ping apple
|
||||
@rustbot ping macos
|
||||
@rustbot ping ios
|
||||
```
|
||||
|
||||
Keep in mind that these aliases are meant to make humans' life easier.
|
||||
|
|
|
|||
|
|
@ -1,90 +0,0 @@
|
|||
# Cleanup Crew
|
||||
|
||||
**Github Label:** [ICEBreaker-Cleanup-Crew] <br>
|
||||
**Ping command:** `@rustbot ping cleanup-crew`
|
||||
|
||||
[ICEBreaker-Cleanup-Crew]: https://github.com/rust-lang/rust/labels/ICEBreaker-Cleanup-Crew
|
||||
|
||||
The "Cleanup Crew" are focused on improving bug reports. Specifically,
|
||||
the goal is to try to ensure that every bug report has all the
|
||||
information that will be needed for someone to fix it:
|
||||
|
||||
* a minimal, standalone example that shows the problem
|
||||
* links to duplicates or related bugs
|
||||
* if the bug is a regression (something that used to work, but no longer does),
|
||||
then a bisection to the PR or nightly that caused the regression
|
||||
|
||||
This kind of cleanup is invaluable in getting bugs fixed. Better
|
||||
still, it can be done by anybody who knows Rust, without any
|
||||
particularly deep knowledge of the compiler.
|
||||
|
||||
Let's look a bit at the workflow for doing "cleanup crew" actions.
|
||||
|
||||
## Finding a minimal, standalone example
|
||||
|
||||
Here the ultimate goal is to produce an example that reproduces the same
|
||||
problem but without relying on any external crates. Such a test ought to contain
|
||||
as little code as possible, as well. This will make it much easier to isolate the problem.
|
||||
|
||||
However, even if the "ultimate minimal test" cannot be achieved, it's
|
||||
still useful to post incremental minimizations. For example, if you
|
||||
can eliminate some of the external dependencies, that is helpful, and
|
||||
so forth.
|
||||
|
||||
It's particularly useful to reduce to an example that works
|
||||
in the [Rust playground](https://play.rust-lang.org/), rather than
|
||||
requiring people to checkout a cargo build.
|
||||
|
||||
There are many resources for how to produce minimized test cases. Here
|
||||
are a few:
|
||||
|
||||
* The [rust-reduce](https://github.com/jethrogb/rust-reduce) tool can try to reduce
|
||||
code automatically.
|
||||
* The [C-reduce](https://github.com/csmith-project/creduce) tool also works
|
||||
on Rust code, though it requires that you start from a single
|
||||
file. (A post explaining how to do it can be found [here](https://insaneinside.net/2017/09/12/whole-crate-bug-reduction-with-creduce.html).)
|
||||
* pnkfelix's [Rust Bug Minimization Patterns] blog post
|
||||
* This post focuses on "heavy bore" techniques, where you are
|
||||
starting with a large, complex cargo project that you wish to
|
||||
narrow down to something standalone.
|
||||
|
||||
[Rust Bug Minimization Patterns]: http://blog.pnkfx.org/blog/2019/11/18/rust-bug-minimization-patterns/
|
||||
|
||||
## Links to duplicate or related bugs
|
||||
|
||||
If you are on the "Cleanup Crew", you will sometimes see multiple bug
|
||||
reports that seem very similar. You can link one to the other just by
|
||||
mentioning the other bug number in a Github comment. Sometimes it is
|
||||
useful to close duplicate bugs. But if you do so, you should always
|
||||
copy any test case from the bug you are closing to the other bug that
|
||||
remains open, as sometimes duplicate-looking bugs will expose
|
||||
different facets of the same problem.
|
||||
|
||||
## Bisecting regressions
|
||||
|
||||
For regressions (something that used to work, but no longer does), it
|
||||
is super useful if we can figure out precisely when the code stopped
|
||||
working. The gold standard is to be able to identify the precise
|
||||
**PR** that broke the code, so we can ping the author, but even
|
||||
narrowing it down to a nightly build is helpful, especially as that
|
||||
then gives us a range of PRs. (One other challenge is that we
|
||||
sometimes land "rollup" PRs, which combine multiple PRs into one.)
|
||||
|
||||
### cargo-bisect-rustc
|
||||
|
||||
To help in figuring out the cause of a regression we have a tool
|
||||
called [cargo-bisect-rustc]. It will automatically download and test
|
||||
various builds of rustc. For recent regressions, it is even able to
|
||||
use the builds from our CI to track down the regression to a specific
|
||||
PR; for older regressions, it will simply identify a nightly.
|
||||
|
||||
To learn to use [cargo-bisect-rustc], check out [this blog post][learn], which
|
||||
gives a quick introduction to how it works. Additionally, there is a [Guide]
|
||||
which goes into more detail on how to use it. You can also ask questions at
|
||||
the Zulip stream [`#t-compiler/cargo-bisect-rustc`][zcbr], or help in
|
||||
improving the tool.
|
||||
|
||||
[cargo-bisect-rustc]: https://github.com/rust-lang/cargo-bisect-rustc/
|
||||
[learn]: https://blog.rust-lang.org/inside-rust/2019/12/18/bisecting-rust-compiler.html
|
||||
[zcbr]: https://rust-lang.zulipchat.com/#narrow/stream/217417-t-compiler.2Fcargo-bisect-rustc
|
||||
[Guide]: https://rust-lang.github.io/cargo-bisect-rustc/
|
||||
|
|
@ -1,38 +0,0 @@
|
|||
# LLVM Icebreakers Notification group
|
||||
|
||||
**Github Label:** [A-LLVM] <br>
|
||||
**Ping command:** `@rustbot ping icebreakers-llvm`
|
||||
|
||||
[A-LLVM]: https://github.com/rust-lang/rust/labels/A-LLVM
|
||||
|
||||
*Note*: this notification group is *not* the same as the LLVM working group
|
||||
(WG-llvm).
|
||||
|
||||
The "LLVM Icebreakers Notification Group" are focused on bugs that center around
|
||||
LLVM. These bugs often arise because of LLVM optimizations gone awry, or as the
|
||||
result of an LLVM upgrade. The goal here is:
|
||||
|
||||
- to determine whether the bug is a result of us generating invalid LLVM IR,
|
||||
or LLVM misoptimizing;
|
||||
- if the former, to fix our IR;
|
||||
- if the latter, to try and file a bug on LLVM (or identify an existing bug).
|
||||
|
||||
The group may also be asked to weigh in on other sorts of LLVM-focused
|
||||
questions.
|
||||
|
||||
## Helpful tips and options
|
||||
|
||||
The ["Debugging LLVM"][d] section of the
|
||||
rustc-dev-guide gives a step-by-step process for how to help debug bugs
|
||||
caused by LLVM. In particular, it discusses how to emit LLVM IR, run
|
||||
the LLVM IR optimization pipelines, and so forth. You may also find
|
||||
it useful to look at the various codegen options listed under `-C help`
|
||||
and the internal options under `-Z help` -- there are a number that
|
||||
pertain to LLVM (just search for LLVM).
|
||||
|
||||
[d]: ../backend/debugging.md
|
||||
|
||||
## If you do narrow to an LLVM bug
|
||||
|
||||
The ["Debugging LLVM"][d] section also describes what to do once
|
||||
you've identified the bug.
|
||||
|
|
@ -270,35 +270,6 @@ in `test.rs` is the function `make_test`, which is where hand-written
|
|||
Some extra reading about `make_test` can be found
|
||||
[here](https://quietmisdreavus.net/code/2018/02/23/how-the-doctests-get-made/).
|
||||
|
||||
## Dotting i's And Crossing t's
|
||||
|
||||
So that's `rustdoc`'s code in a nutshell, but there's more things in the
|
||||
compiler that deal with it. Since we have the full `compiletest` suite at hand,
|
||||
there's a set of tests in `tests/rustdoc` that make sure the final `HTML` is
|
||||
what we expect in various situations. These tests also use a supplementary
|
||||
script, `src/etc/htmldocck.py`, that allows it to look through the final `HTML`
|
||||
using `XPath` notation to get a precise look at the output. The full
|
||||
description of all the commands available to `rustdoc` tests (e.g. [`@has`] and
|
||||
[`@matches`]) is in [`htmldocck.py`].
|
||||
|
||||
To use multiple crates in a `rustdoc` test, add `//@ aux-build:filename.rs`
|
||||
to the top of the test file. `filename.rs` should be placed in an `auxiliary`
|
||||
directory relative to the test file with the comment. If you need to build
|
||||
docs for the auxiliary file, use `//@ build-aux-docs`.
|
||||
|
||||
In addition, there are separate tests for the search index and `rustdoc`'s
|
||||
ability to query it. The files in `tests/rustdoc-js` each contain a
|
||||
different search query and the expected results, broken out by search tab.
|
||||
These files are processed by a script in `src/tools/rustdoc-js` and the `Node.js`
|
||||
runtime. These tests don't have as thorough of a writeup, but a broad example
|
||||
that features results in all tabs can be found in `basic.js`. The basic idea is
|
||||
that you match a given `QUERY` with a set of `EXPECTED` results, complete with
|
||||
the full item path of each item.
|
||||
|
||||
[`@has`]: https://github.com/rust-lang/rust/blob/master/src/etc/htmldocck.py#L39
|
||||
[`@matches`]: https://github.com/rust-lang/rust/blob/master/src/etc/htmldocck.py#L44
|
||||
[`htmldocck.py`]: https://github.com/rust-lang/rust/blob/master/src/etc/htmldocck.py
|
||||
|
||||
## Testing Locally
|
||||
|
||||
Some features of the generated `HTML` documentation might require local
|
||||
|
|
|
|||
|
|
@ -0,0 +1,14 @@
|
|||
# The `rustdoc-gui` test suite
|
||||
|
||||
> **FIXME**: This section is a stub. Please help us flesh it out!
|
||||
|
||||
This page is about the test suite named `rustdoc-gui` used to test the "GUI" of `rustdoc` (i.e., the HTML/JS/CSS as rendered in a browser).
|
||||
For other rustdoc-specific test suites, see [Rustdoc test suites].
|
||||
|
||||
These use a NodeJS-based tool called [`browser-UI-test`] that uses [puppeteer] to run tests in a headless browser and check rendering and interactivity. For information on how to write this form of test, see [`tests/rustdoc-gui/README.md`][rustdoc-gui-readme] as well as [the description of the `.goml` format][goml-script]
|
||||
|
||||
[Rustdoc test suites]: ../tests/compiletest.md#rustdoc-test-suites
|
||||
[`browser-UI-test`]: https://github.com/GuillaumeGomez/browser-UI-test/
|
||||
[puppeteer]: https://pptr.dev/
|
||||
[rustdoc-gui-readme]: https://github.com/rust-lang/rust/blob/master/tests/rustdoc-gui/README.md
|
||||
[goml-script]: https://github.com/GuillaumeGomez/browser-UI-test/blob/master/goml-script.md
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
# The `rustdoc-json` test suite
|
||||
|
||||
> **FIXME**: This section is a stub. It will be populated by [PR #2422](https://github.com/rust-lang/rustc-dev-guide/pull/2422/).
|
||||
|
|
@ -1,112 +1,191 @@
|
|||
# The `rustdoc` test suite
|
||||
|
||||
This page is specifically about the test suite named `rustdoc`.
|
||||
For other test suites used for testing rustdoc, see [Rustdoc tests](../rustdoc.md#tests).
|
||||
This page is about the test suite named `rustdoc` used to test the HTML output of `rustdoc`.
|
||||
For other rustdoc-specific test suites, see [Rustdoc test suites].
|
||||
|
||||
The `rustdoc` test suite is specifically used to test the HTML output of rustdoc.
|
||||
Each test file in this test suite is simply a Rust source file `file.rs` sprinkled with
|
||||
so-called *directives* located inside normal Rust code comments.
|
||||
These come in two flavors: *Compiletest* and *HtmlDocCk*.
|
||||
|
||||
This is achieved by means of `htmldocck.py`, a custom checker script that leverages [XPath].
|
||||
To learn more about the former, read [Compiletest directives].
|
||||
For the latter, continue reading.
|
||||
|
||||
[XPath]: https://en.wikipedia.org/wiki/XPath
|
||||
Internally, [`compiletest`] invokes the supplementary checker script [`htmldocck.py`].
|
||||
|
||||
## Directives
|
||||
Directives to htmldocck are similar to those given to `compiletest` in that they take the form of `//@` comments.
|
||||
[Rustdoc test suites]: ../tests/compiletest.md#rustdoc-test-suites
|
||||
[`compiletest`]: ../tests/compiletest.md
|
||||
[`htmldocck.py`]: https://github.com/rust-lang/rust/blob/master/src/etc/htmldocck.py
|
||||
|
||||
In addition to the directives listed here,
|
||||
`rustdoc` tests also support most
|
||||
[compiletest directives](../tests/directives.html).
|
||||
## HtmlDocCk Directives
|
||||
|
||||
All `PATH`s in directives are relative to the rustdoc output directory (`build/TARGET/test/rustdoc/TESTNAME`),
|
||||
so it is conventional to use a `#![crate_name = "foo"]` attribute to avoid
|
||||
having to write a long crate name multiple times.
|
||||
To avoid repetition, `-` can be used in any `PATH` argument to re-use the previous `PATH` argument.
|
||||
Directives to HtmlDocCk are assertions that place constraints on the generated HTML.
|
||||
They look similar to those given to `compiletest` in that they take the form of `//@` comments
|
||||
but ultimately, they are completey distinct and processed by different programs.
|
||||
|
||||
All arguments take the form of quoted strings
|
||||
(both single and double quotes are supported),
|
||||
[XPath] is used to query parts of the HTML document tree.
|
||||
|
||||
**Introductory example**:
|
||||
|
||||
```rust,ignore (illustrative)
|
||||
//@ has file/type.Alias.html
|
||||
//@ has - '//*[@class="rust item-decl"]//code' 'type Alias = Option<i32>;'
|
||||
pub type Alias = Option<i32>;
|
||||
```
|
||||
|
||||
Here, we check that documentation generated for crate `file` contains a page for the
|
||||
public type alias `Alias` where the code block that is found at the top contains the
|
||||
expected rendering of the item. The `//*[@class="rust item-decl"]//code` is an XPath
|
||||
expression.
|
||||
|
||||
Conventionally, you place these directives directly above the thing they are meant to test.
|
||||
Technically speaking however, they don't need to be as HtmlDocCk only looks for the directives.
|
||||
|
||||
All directives take a `PATH` argument.
|
||||
To avoid repetition, `-` can be passed to it to re-use the previous `PATH` argument.
|
||||
Since the path contains the name of the crate, it is conventional to add a
|
||||
`#![crate_name = "foo"]` attribute to the crate root to shorten the resulting path.
|
||||
|
||||
All arguments take the form of shell-style (single or double) quoted strings,
|
||||
with the exception of `COUNT` and the special `-` form of `PATH`.
|
||||
|
||||
Directives are assertions that place constraints on the generated HTML.
|
||||
|
||||
All directives (except `files`) can be negated by putting a `!` in front of their name.
|
||||
All directives (except `files`) can be *negated* by putting a `!` in front of their name.
|
||||
Before you add negated directives, please read about [their caveats](#caveats).
|
||||
|
||||
Similar to shell commands,
|
||||
directives can extend across multiple lines if their last char is `\`.
|
||||
In this case, the start of the next line should be `//`, with no `@`.
|
||||
|
||||
For example, `//@ !has 'foo/struct.Bar.html'` checks that crate `foo` does not have a page for a struct named `Bar` in the crate root.
|
||||
Use the special string `{{channel}}` in XPaths, `PATTERN` arguments and [snapshot files](#snapshot)
|
||||
if you'd like to refer to the URL `https://doc.rust-lang.org/CHANNEL` where `CHANNEL` refers to the
|
||||
current release channel (e.g, `stable` or `nightly`).
|
||||
|
||||
Listed below are all possible directives:
|
||||
|
||||
[XPath]: https://en.wikipedia.org/wiki/XPath
|
||||
|
||||
### `has`
|
||||
|
||||
Usage 1: `//@ has PATH`
|
||||
Usage 2: `//@ has PATH XPATH PATTERN`
|
||||
> Usage 1: `//@ has PATH`
|
||||
|
||||
In the first form, `has` checks that a given file exists.
|
||||
Check that the file given by `PATH` exists.
|
||||
|
||||
In the second form, `has` is an alias for `matches`,
|
||||
except `PATTERN` is a whitespace-normalized[^1] string instead of a regex.
|
||||
> Usage 2: `//@ has PATH XPATH PATTERN`
|
||||
|
||||
### `matches`
|
||||
Checks that the text of each element / attribute / text selected by `XPATH` in the
|
||||
whitespace-normalized[^1] file given by `PATH` matches the
|
||||
(also whitespace-normalized) string `PATTERN`.
|
||||
|
||||
Usage: `//@ matches PATH XPATH PATTERN`
|
||||
|
||||
Checks that the text of each element selected by `XPATH` in `PATH` matches the python-flavored regex `PATTERN`.
|
||||
|
||||
### `matchesraw`
|
||||
|
||||
Usage: `//@ matchesraw PATH PATTERN`
|
||||
|
||||
Checks that the contents of the file `PATH` matches the regex `PATTERN`.
|
||||
**Tip**: If you'd like to avoid whitespace normalization and/or if you'd like to match with a regex,
|
||||
use `matches` instead.
|
||||
|
||||
### `hasraw`
|
||||
|
||||
Usage: `//@ hasraw PATH PATTERN`
|
||||
> Usage: `//@ hasraw PATH PATTERN`
|
||||
|
||||
Same as `matchesraw`, except `PATTERN` is a whitespace-normalized[^1] string instead of a regex.
|
||||
Checks that the contents of the whitespace-normalized[^1] file given by `PATH`
|
||||
matches the (also whitespace-normalized) string `PATTERN`.
|
||||
|
||||
**Tip**: If you'd like to avoid whitespace normalization and / or if you'd like to match with a
|
||||
regex, use `matchesraw` instead.
|
||||
|
||||
### `matches`
|
||||
|
||||
> Usage: `//@ matches PATH XPATH PATTERN`
|
||||
|
||||
Checks that the text of each element / attribute / text selected by `XPATH` in the
|
||||
file given by `PATH` matches the Python-flavored[^2] regex `PATTERN`.
|
||||
|
||||
### `matchesraw`
|
||||
|
||||
> Usage: `//@ matchesraw PATH PATTERN`
|
||||
|
||||
Checks that the contents of the file given by `PATH` matches the
|
||||
Python-flavored[^2] regex `PATTERN`.
|
||||
|
||||
### `count`
|
||||
|
||||
Usage: `//@ count PATH XPATH COUNT`
|
||||
> Usage: `//@ count PATH XPATH COUNT`
|
||||
|
||||
Checks that there are exactly `COUNT` matches for `XPATH` within the file `PATH`.
|
||||
Checks that there are exactly `COUNT` matches for `XPATH` within the file given by `PATH`.
|
||||
|
||||
### `snapshot`
|
||||
|
||||
Usage: `//@ snapshot NAME PATH XPATH`
|
||||
> Usage: `//@ snapshot NAME PATH XPATH`
|
||||
|
||||
Creates a snapshot test named NAME.
|
||||
A snapshot test captures a subtree of the DOM, at the location
|
||||
determined by the XPath, and compares it to a pre-recorded value
|
||||
in a file. The file's name is the test's name with the `.rs` extension
|
||||
replaced with `.NAME.html`, where NAME is the snapshot's name.
|
||||
Checks that the element / text selected by `XPATH` in the file given by `PATH` matches the
|
||||
pre-recorded subtree or text (the "snapshot") in file `FILE_STEM.NAME.html` where `FILE_STEM`
|
||||
is the file stem of the test file.
|
||||
|
||||
htmldocck supports the `--bless` option to accept the current subtree
|
||||
as expected, saving it to the file determined by the snapshot's name.
|
||||
compiletest's `--bless` flag is forwarded to htmldocck.
|
||||
Pass the `--bless` option to `compiletest` to accept the current subtree/text as expected.
|
||||
This will overwrite the aforementioned file (or create it if it doesn't exist). It will
|
||||
automatically normalize the channel-dependent URL `https://doc.rust-lang.org/CHANNEL` to
|
||||
the special string `{{channel}}`.
|
||||
|
||||
### `has-dir`
|
||||
|
||||
Usage: `//@ has-dir PATH`
|
||||
> Usage: `//@ has-dir PATH`
|
||||
|
||||
Checks for the existence of directory `PATH`.
|
||||
Checks for the existence of the directory given by `PATH`.
|
||||
|
||||
### `files`
|
||||
|
||||
Usage: `//@ files PATH ENTRIES`
|
||||
> Usage: `//@ files PATH ENTRIES`
|
||||
|
||||
Checks that the directory `PATH` contains exactly `ENTRIES`.
|
||||
`ENTRIES` is a python list of strings inside a quoted string,
|
||||
as if it were to be parsed by `eval`.
|
||||
(note that the list is actually parsed by `shlex.split`,
|
||||
so it cannot contain arbitrary python expressions).
|
||||
Checks that the directory given by `PATH` contains exactly `ENTRIES`.
|
||||
`ENTRIES` is a Python-like list of strings inside a quoted string.
|
||||
|
||||
Example: `//@ files "foo/bar" '["index.html", "sidebar-items.js"]'`
|
||||
**Example**: `//@ files "foo/bar" '["index.html", "sidebar-items.js"]'`
|
||||
|
||||
[^1]: Whitespace normalization means that all spans of consecutive whitespace are replaced with a single space. The files themselves are also whitespace-normalized.
|
||||
[^1]: Whitespace normalization means that all spans of consecutive whitespace are replaced with a single space.
|
||||
[^2]: They are Unicode aware (flag `UNICODE` is set), match case-sensitively and in single-line mode.
|
||||
|
||||
## Compiletest Directives (Brief)
|
||||
|
||||
As mentioned in the introduction, you also have access to [compiletest directives].
|
||||
Most importantly, they allow you to register auxiliary crates and
|
||||
to pass flags to the `rustdoc` binary under test.
|
||||
It's *strongly recommended* to read that chapter if you don't know anything about them yet.
|
||||
|
||||
Here are some details that are relevant to this test suite specifically:
|
||||
|
||||
* While you can use both `//@ compile-flags` and `//@ doc-flags` to pass flags to `rustdoc`,
|
||||
prefer to user the latter to show intent. The former is meant for `rustc`.
|
||||
* Add `//@ build-aux-docs` to the test file that has auxiliary crates to not only compile the
|
||||
auxiliaries with `rustc` but to also document them with `rustdoc`.
|
||||
|
||||
## Caveats
|
||||
|
||||
Testing for the absence of an element or a piece of text is quite fragile and not very future proof.
|
||||
|
||||
It's not unusual that the *shape* of the generated HTML document tree changes from time to time.
|
||||
This includes for example renamings of CSS classes.
|
||||
|
||||
Whenever that happens, *positive* checks will either continue to match the intended element /
|
||||
attribute / text (if their XPath expression is general / loose enough) and
|
||||
thus continue to test the correct thing or they won't in which case they would fail thereby
|
||||
forcing the author of the change to look at them.
|
||||
|
||||
Compare that to *negative* checks (e.g., `//@ !has PATH XPATH PATTERN`) which won't fail if their
|
||||
XPath expression "no longer" matches. The author who changed "the shape" thus won't get notified and
|
||||
as a result someone else can unintentionally reintroduce `PATTERN` into the generated docs without
|
||||
the original negative check failing.
|
||||
|
||||
**Note**: Please avoid the use of *negated* checks!
|
||||
|
||||
**Tip**: If you can't avoid it, please **always** pair it with an analogous positive check in the
|
||||
immediate vicinity, so people changing "the shape" have a chance to notice and to update the
|
||||
negated check!
|
||||
|
||||
## Limitations
|
||||
`htmldocck.py` uses the xpath implementation from the standard library.
|
||||
|
||||
HtmlDocCk uses the XPath implementation from the Python standard library.
|
||||
This leads to several limitations:
|
||||
|
||||
* All `XPATH` arguments must start with `//` due to a flaw in the implementation.
|
||||
* Many XPath features (functions, axies, etc.) are not supported.
|
||||
* Only well-formed HTML can be parsed (hopefully rustdoc doesn't output mismatched tags).
|
||||
|
||||
Furthmore, compiletest [revisions] are not supported.
|
||||
|
||||
[revisions]: ../tests/compiletest.md#revisions
|
||||
[compiletest directives]: ../tests/directives.md
|
||||
|
|
|
|||
|
|
@ -67,43 +67,29 @@ does is call the `main()` that's in this crate's `lib.rs`, though.)
|
|||
|
||||
## Code structure
|
||||
|
||||
* All paths in this section are relative to `src/librustdoc` in the rust-lang/rust repository.
|
||||
All paths in this section are relative to `src/librustdoc/` in the rust-lang/rust repository.
|
||||
|
||||
* Most of the HTML printing code is in `html/format.rs` and `html/render/mod.rs`.
|
||||
It's in a bunch of `fmt::Display` implementations and supplementary
|
||||
functions.
|
||||
* The types that got `Display` impls above are defined in `clean/mod.rs`, right
|
||||
next to the custom `Clean` trait used to process them out of the rustc HIR.
|
||||
It's in a bunch of functions returning `impl std::fmt::Display`.
|
||||
* The data types that get rendered by the functions mentioned above are defined in `clean/types.rs`.
|
||||
The functions responsible for creating them from the `HIR` and the `rustc_middle::ty` IR
|
||||
live in `clean/mod.rs`.
|
||||
* The bits specific to using rustdoc as a test harness are in
|
||||
`doctest.rs`.
|
||||
* The Markdown renderer is loaded up in `html/markdown.rs`, including functions
|
||||
for extracting doctests from a given block of Markdown.
|
||||
* Frontend CSS and JavaScript are stored in `html/static/`.
|
||||
* Re. JavaScript, type annotations are written using [TypeScript-flavored JSDoc]
|
||||
comments and an external `.d.ts` file.
|
||||
This way, the code itself remains plain, valid JavaScript.
|
||||
We only use `tsc` as a linter.
|
||||
|
||||
[TypeScript-flavored JSDoc]: https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html
|
||||
|
||||
## Tests
|
||||
|
||||
* Tests on search engine and index are located in `tests/rustdoc-js` and `tests/rustdoc-js-std`.
|
||||
The format is specified
|
||||
[in the search guide](rustdoc-internals/search.md#testing-the-search-engine).
|
||||
* Tests on the "UI" of rustdoc (the terminal output it produces when run) are in
|
||||
`tests/rustdoc-ui`
|
||||
* Tests on the "GUI" of rustdoc (the HTML, JS, and CSS as rendered in a browser)
|
||||
are in `tests/rustdoc-gui`. These use a [NodeJS tool called
|
||||
browser-UI-test](https://github.com/GuillaumeGomez/browser-UI-test/) that uses
|
||||
puppeteer to run tests in a headless browser and check rendering and
|
||||
interactivity. For information on how to write this form of test,
|
||||
see [`tests/rustdoc-gui/README.md`][rustdoc-gui-readme]
|
||||
as well as [the description of the `.goml` format][goml-script]
|
||||
* Tests on the structure of rustdoc HTML output are located in `tests/rustdoc`,
|
||||
where they're handled by the test runner of bootstrap and
|
||||
the supplementary script `src/etc/htmldocck.py`.
|
||||
[These tests have several extra directives available to them](./rustdoc-internals/rustdoc-test-suite.md).
|
||||
* Additionally, JavaScript type annotations are written using [TypeScript-flavored JSDoc]
|
||||
comments and an external d.ts file. The code itself is plain, valid JavaScript; we only
|
||||
use tsc as a linter.
|
||||
|
||||
[TypeScript-flavored JSDoc]: https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html
|
||||
[rustdoc-gui-readme]: https://github.com/rust-lang/rust/blob/master/tests/rustdoc-gui/README.md
|
||||
[goml-script]: https://github.com/GuillaumeGomez/browser-UI-test/blob/master/goml-script.md
|
||||
`rustdoc`'s integration tests are split across several test suites.
|
||||
See [Rustdoc tests suites](tests/compiletest.md#rustdoc-test-suites) for more details.
|
||||
|
||||
## Constraints
|
||||
|
||||
|
|
|
|||
|
|
@ -186,9 +186,11 @@ Note that if you start the default try job using `@bors try`, it will skip build
|
|||
Multiple try builds can execute concurrently across different PRs.
|
||||
|
||||
<div class="warning">
|
||||
bors identify try jobs by commit hash. This means that if you have two PRs
|
||||
|
||||
Bors identifies try jobs by commit hash. This means that if you have two PRs
|
||||
containing the same (latest) commits, running `@bors try` will result in the
|
||||
*same* try job and it really confuses `bors`. Please refrain from doing so.
|
||||
|
||||
</div>
|
||||
|
||||
[rustc-perf]: https://github.com/rust-lang/rustc-perf
|
||||
|
|
|
|||
|
|
@ -56,6 +56,9 @@ incremental compilation. The various suites are defined in
|
|||
|
||||
The following test suites are available, with links for more information:
|
||||
|
||||
[`tests`]: https://github.com/rust-lang/rust/blob/master/tests
|
||||
[`src/tools/compiletest/src/common.rs`]: https://github.com/rust-lang/rust/tree/master/src/tools/compiletest/src/common.rs
|
||||
|
||||
### Compiler-specific test suites
|
||||
|
||||
| Test suite | Purpose |
|
||||
|
|
@ -71,6 +74,7 @@ The following test suites are available, with links for more information:
|
|||
| [`mir-opt`](#mir-opt-tests) | Check MIR generation and optimizations |
|
||||
| [`coverage`](#coverage-tests) | Check coverage instrumentation |
|
||||
| [`coverage-run-rustdoc`](#coverage-tests) | `coverage` tests that also run instrumented doctests |
|
||||
| [`crashes`](#crashes-tests) | Check that the compiler ICEs/panics/crashes on certain inputs to catch accidental fixes |
|
||||
|
||||
### General purpose test suite
|
||||
|
||||
|
|
@ -78,19 +82,23 @@ The following test suites are available, with links for more information:
|
|||
|
||||
### Rustdoc test suites
|
||||
|
||||
See [Rustdoc tests](../rustdoc.md#tests) for more details.
|
||||
| Test suite | Purpose |
|
||||
|--------------------------------------|--------------------------------------------------------------------------|
|
||||
| [`rustdoc`][rustdoc-html-tests] | Check HTML output of `rustdoc` |
|
||||
| [`rustdoc-gui`][rustdoc-gui-tests] | Check `rustdoc`'s GUI using a web browser |
|
||||
| [`rustdoc-js`][rustdoc-js-tests] | Check `rustdoc`'s search engine and index |
|
||||
| [`rustdoc-js-std`][rustdoc-js-tests] | Check `rustdoc`'s search engine and index on the std library docs |
|
||||
| [`rustdoc-json`][rustdoc-json-tests] | Check JSON output of `rustdoc` |
|
||||
| `rustdoc-ui` | Check terminal output of `rustdoc` ([see also](ui.md)) |
|
||||
|
||||
| Test suite | Purpose |
|
||||
|------------------|--------------------------------------------------------------------------|
|
||||
| `rustdoc` | Check `rustdoc` generated files contain the expected documentation |
|
||||
| `rustdoc-gui` | Check `rustdoc`'s GUI using a web browser |
|
||||
| `rustdoc-js` | Check `rustdoc` search is working as expected |
|
||||
| `rustdoc-js-std` | Check rustdoc search is working as expected specifically on the std docs |
|
||||
| `rustdoc-json` | Check JSON output of `rustdoc` |
|
||||
| `rustdoc-ui` | Check terminal output of `rustdoc` |
|
||||
Some rustdoc-specific tests can also be found in `ui/rustdoc/`.
|
||||
These check rustdoc-related or -specific lints that (also) run as part of `rustc`, not (only) `rustdoc`.
|
||||
Run-make tests pertaining to rustdoc are typically named `run-make/rustdoc-*/`.
|
||||
|
||||
[`tests`]: https://github.com/rust-lang/rust/blob/master/tests
|
||||
[`src/tools/compiletest/src/common.rs`]: https://github.com/rust-lang/rust/tree/master/src/tools/compiletest/src/common.rs
|
||||
[rustdoc-html-tests]: ../rustdoc-internals/rustdoc-test-suite.md
|
||||
[rustdoc-gui-tests]: ../rustdoc-internals/rustdoc-gui-test-suite.md
|
||||
[rustdoc-js-tests]: ../rustdoc-internals/search.md#testing-the-search-engine
|
||||
[rustdoc-json-tests]: ../rustdoc-internals/rustdoc-json-test-suite.md
|
||||
|
||||
### Pretty-printer tests
|
||||
|
||||
|
|
@ -107,7 +115,7 @@ default behavior without any commands is to:
|
|||
2. Run `rustc -Zunpretty=normal` on the output of the previous step.
|
||||
3. The output of the previous two steps should be the same.
|
||||
4. Run `rustc -Zno-codegen` on the output to make sure that it can type check
|
||||
(this is similar to running `cargo check`).
|
||||
(similar to `cargo check`).
|
||||
|
||||
If any of the commands above fail, then the test fails.
|
||||
|
||||
|
|
@ -438,7 +446,9 @@ To work around this when working on a particular test, temporarily create a
|
|||
with these contents:
|
||||
|
||||
<div class="warning">
|
||||
|
||||
Be careful not to add this `Cargo.toml` or its `Cargo.lock` to your actual PR!
|
||||
|
||||
</div>
|
||||
|
||||
```toml
|
||||
|
|
|
|||
|
|
@ -202,6 +202,7 @@ settings:
|
|||
`//@ needs-crate-type: cdylib, proc-macro` will cause the test to be ignored
|
||||
on `wasm32-unknown-unknown` target because the target does not support the
|
||||
`proc-macro` crate type.
|
||||
- `needs-target-std` — ignores if target platform does not have std support.
|
||||
|
||||
The following directives will check LLVM support:
|
||||
|
||||
|
|
@ -248,18 +249,20 @@ ignoring debuggers.
|
|||
| `no-prefer-dynamic` | Don't use `-C prefer-dynamic`, don't build as a dylib via a `--crate-type=dylib` preset flag | `ui`, `crashes` | N/A |
|
||||
|
||||
<div class="warning">
|
||||
|
||||
Tests (outside of `run-make`) that want to use incremental tests not in the
|
||||
incremental test-suite must not pass `-C incremental` via `compile-flags`, and
|
||||
must instead use the `//@ incremental` directive.
|
||||
|
||||
Consider writing the test as a proper incremental test instead.
|
||||
|
||||
</div>
|
||||
|
||||
### Rustdoc
|
||||
|
||||
| Directive | Explanation | Supported test suites | Possible values |
|
||||
|-------------|--------------------------------------------------------------|------------------------------------------|---------------------------|
|
||||
| `doc-flags` | Flags passed to `rustdoc` when building the test or aux file | `rustdoc`, `rustdoc-js`, `rustdoc-json` | Any valid `rustdoc` flags |
|
||||
| `doc-flags` | Flags passed to `rustdoc` when building the test or aux file | `rustdoc`, `rustdoc-js`, `rustdoc-json` | Any valid `rustdoc` flags |
|
||||
|
||||
<!--
|
||||
**FIXME(rustdoc)**: what does `check-test-line-numbers-match` do?
|
||||
|
|
@ -267,6 +270,17 @@ Asked in
|
|||
<https://rust-lang.zulipchat.com/#narrow/stream/266220-t-rustdoc/topic/What.20is.20the.20.60check-test-line-numbers-match.60.20directive.3F>.
|
||||
-->
|
||||
|
||||
#### Test-suite-specific directives
|
||||
|
||||
The test suites [`rustdoc`][rustdoc-html-tests], [`rustdoc-js`/`rustdoc-js-std`][rustdoc-js-tests]
|
||||
and [`rustdoc-json`][rustdoc-json-tests] each feature an additional set of directives whose basic
|
||||
syntax resembles the one of compiletest directives but which are ultimately read and checked by
|
||||
separate tools. For more information, please read their respective chapters as linked above.
|
||||
|
||||
[rustdoc-html-tests]: ../rustdoc-internals/rustdoc-test-suite.md
|
||||
[rustdoc-js-tests]: ../rustdoc-internals/search.html#testing-the-search-engine
|
||||
[rustdoc-json-tests]: ../rustdoc-internals/rustdoc-json-test-suite.md
|
||||
|
||||
### Pretty printing
|
||||
|
||||
See [Pretty-printer](compiletest.md#pretty-printer-tests).
|
||||
|
|
|
|||
|
|
@ -7,9 +7,11 @@ ui/codegen/assembly test suites. It provides `core` stubs for tests that need to
|
|||
build for cross-compiled targets but do not need/want to run.
|
||||
|
||||
<div class="warning">
|
||||
|
||||
Please note that [`minicore`] is only intended for `core` items, and explicitly
|
||||
**not** `std` or `alloc` items because `core` items are applicable to a wider
|
||||
range of tests.
|
||||
|
||||
</div>
|
||||
|
||||
A test can use [`minicore`] by specifying the `//@ add-core-stubs` directive.
|
||||
|
|
|
|||
|
|
@ -8,6 +8,7 @@ development because it takes a really long time. For local development, see the
|
|||
subsection after on how to run a subset of tests.
|
||||
|
||||
<div class="warning">
|
||||
|
||||
Running plain `./x test` will build the stage 1 compiler and then run the whole
|
||||
test suite. This not only include `tests/`, but also `library/`, `compiler/`,
|
||||
`src/tools/` package tests and more.
|
||||
|
|
@ -16,6 +17,7 @@ You usually only want to run a subset of the test suites (or even a smaller set
|
|||
of tests than that) which you expect will exercise your changes. PR CI exercises
|
||||
a subset of test collections, and merge queue CI will exercise all of the test
|
||||
collection.
|
||||
|
||||
</div>
|
||||
|
||||
```text
|
||||
|
|
@ -116,8 +118,10 @@ By listing which test suites you want to run,
|
|||
you avoid having to run tests for components you did not change at all.
|
||||
|
||||
<div class="warning">
|
||||
|
||||
Note that bors only runs the tests with the full stage 2 build; therefore, while
|
||||
the tests **usually** work fine with stage 1, there are some limitations.
|
||||
|
||||
</div>
|
||||
|
||||
### Run all tests using a stage 2 compiler
|
||||
|
|
|
|||
|
|
@ -220,8 +220,12 @@ negligible (i.e. there is no semantic difference between `//~ ERROR` and
|
|||
`//~ERROR` although the former is more common in the codebase).
|
||||
|
||||
`~? <diagnostic kind>` (example being `~? ERROR`)
|
||||
is used to match diagnostics without line information.
|
||||
These can be placed on any line in the test file, but are conventionally placed at the end.
|
||||
is used to match diagnostics _without_ line info at all,
|
||||
or where the line info is outside the main test file[^main test file].
|
||||
These annotations can be placed on any line in the test file.
|
||||
|
||||
[^main test file]: This is a file that has the `~?` annotations,
|
||||
as distinct from aux files, or sources that we have no control over.
|
||||
|
||||
### Error annotation examples
|
||||
|
||||
|
|
|
|||
|
|
@ -72,6 +72,23 @@ days-threshold = 7
|
|||
# Documentation at: https://forge.rust-lang.org/triagebot/pr-assignment.html
|
||||
[assign]
|
||||
|
||||
# NOTE: do not add `[assign.owners]` if we still wish to keep the opt-in
|
||||
# reviewer model, as `[assign.owners]` will cause triagebot auto-reviewer
|
||||
# assignment to kick in.
|
||||
|
||||
# Custom PR welcome message for when no auto reviewer assignment is performed
|
||||
# and no explicit manual reviewer selection is made.
|
||||
# Documentation at: https://forge.rust-lang.org/triagebot/pr-assignment.html#custom-welcome-messages
|
||||
[assign.custom_welcome_messages]
|
||||
welcome-message = ""
|
||||
welcome-message-no-reviewer = """\
|
||||
Thanks for the PR. If you have write access, feel free to merge this PR if it \
|
||||
does not need reviews. You can request a review using `r? rustc-dev-guide` or \
|
||||
`r? <username>`.
|
||||
"""
|
||||
|
||||
# Groups for `r? <group>`.
|
||||
# Documentation at: https://forge.rust-lang.org/triagebot/pr-assignment.html#usage
|
||||
# Keep members alphanumerically sorted.
|
||||
[assign.adhoc_groups]
|
||||
rustc-dev-guide = [
|
||||
|
|
|
|||
Loading…
Reference in New Issue