You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: src/appendix-glossary.md
+3-1
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,8 @@
1
1
# Appendix C: Glossary
2
2
3
-
The compiler uses a number of...idiosyncratic abbreviations and things. This glossary attempts to list them and give you a few pointers for understanding them better.
3
+
The compiler uses a number of...idiosyncratic abbreviations and things. This
4
+
glossary attempts to list them and give you a few pointers for understanding
Copy file name to clipboardExpand all lines: src/compiletest.md
+114-61
Original file line number
Diff line number
Diff line change
@@ -1,42 +1,66 @@
1
1
# `compiletest`
2
+
2
3
## Introduction
4
+
3
5
`compiletest` is the main test harness of the Rust test suite. It allows
4
6
test authors to organize large numbers of tests (the Rust compiler has many
5
7
thousands), efficient test execution (parallel execution is supported), and
6
8
allows the test author to configure behavior and expected results of both
7
9
individual and groups of tests.
8
10
9
-
`compiletest` tests may check test code for success, for failure or in some cases, even failure to compile. Tests are
10
-
typically organized as a Rust source file with annotations in comments before and/or within the test code, which serve to
11
-
direct `compiletest` on if or how to run the test, what behavior to expect, and more. If you are unfamiliar with the compiler
12
-
testing framework, see [`this chapter`](./tests/intro.html) for additional background.
13
-
14
-
The tests themselves are typically (but not always) organized into "suites"--for example, `run-pass`, a folder
15
-
representing tests that should succeed, `run-fail`, a folder holding tests that should compile successfully, but return
16
-
a failure (non-zero status), `compile-fail`, a folder holding tests that should fail to compile, and many more. The various
17
-
suites are defined in [src/tools/compiletest/src/common.rs](https://github.com/rust-lang/rust/tree/master/src/tools/compiletest/src/common.rs) in the `pub struct Config` declaration. And a very good
18
-
introduction to the different suites of compiler tests along with details about them can be found in [`Adding new tests`](./tests/adding.html).
11
+
`compiletest` tests may check test code for success, for failure or in some
12
+
cases, even failure to compile. Tests are typically organized as a Rust source
13
+
file with annotations in comments before and/or within the test code, which
14
+
serve to direct `compiletest` on if or how to run the test, what behavior to
15
+
expect, and more. If you are unfamiliar with the compiler testing framework,
16
+
see [`this chapter`](./tests/intro.html) for additional background.
17
+
18
+
The tests themselves are typically (but not always) organized into
19
+
"suites"--for example, `run-pass`, a folder representing tests that should
20
+
succeed, `run-fail`, a folder holding tests that should compile successfully,
21
+
but return a failure (non-zero status), `compile-fail`, a folder holding tests
22
+
that should fail to compile, and many more. The various suites are defined in
23
+
[src/tools/compiletest/src/common.rs][common] in the `pub struct Config`
24
+
declaration. And a very good introduction to the different suites of compiler
25
+
tests along with details about them can be found in [`Adding new
26
+
tests`](./tests/adding.html).
19
27
20
28
## Adding a new test file
21
-
Briefly, simply create your new test in the appropriate location under [src/test](https://github.com/rust-lang/rust/tree/master/src/test). No registration of test files is necessary as
22
-
`compiletest` will scan the [src/test](https://github.com/rust-lang/rust/tree/master/src/test) subfolder recursively, and will execute any Rust source files it finds as tests.
23
-
See [`Adding new tests`](./tests/adding.html) for a complete guide on how to adding new tests.
29
+
30
+
Briefly, simply create your new test in the appropriate location under
31
+
[src/test][test]. No registration of test files is necessary as `compiletest`
32
+
will scan the [src/test][test] subfolder recursively, and will execute any Rust
33
+
source files it finds as tests. See [`Adding new tests`](./tests/adding.html)
34
+
for a complete guide on how to adding new tests.
24
35
25
36
## Header Commands
26
-
Source file annotations which appear in comments near the top of the source file *before* any test code are known as header
27
-
commands. These commands can instruct `compiletest` to ignore this test, set expectations on whether it is expected to
28
-
succeed at compiling, or what the test's return code is expected to be. Header commands (and their inline counterparts,
29
-
Error Info commands) are described more fully [here](./tests/adding.html#header-commands-configuring-rustc).
37
+
38
+
Source file annotations which appear in comments near the top of the source
39
+
file *before* any test code are known as header commands. These commands can
40
+
instruct `compiletest` to ignore this test, set expectations on whether it is
41
+
expected to succeed at compiling, or what the test's return code is expected to
42
+
be. Header commands (and their inline counterparts, Error Info commands) are
Header commands are defined in the `TestProps` struct in [src/tools/compiletest/src/header.rs](https://github.com/rust-lang/rust/tree/master/src/tools/compiletest/src/header.rs). At a high level, there are dozens of test properties defined here, all set to default values in the `TestProp` struct's `impl` block. Any test can override this
33
-
default value by specifying the property in question as header command as a comment (`//`) in the test source file, before any source code.
47
+
48
+
Header commands are defined in the `TestProps` struct in
49
+
[src/tools/compiletest/src/header.rs][header]. At a high level, there are
50
+
dozens of test properties defined here, all set to default values in the
51
+
`TestProp` struct's `impl` block. Any test can override this default value by
52
+
specifying the property in question as header command as a comment (`//`) in
53
+
the test source file, before any source code.
34
54
35
55
#### Using a header command
36
-
Here is an example, specifying the `must-compile-successfully` header command, which takes no arguments, followed by the
37
-
`failure-status` header command, which takes a single argument (which, in this case is a value of 1). `failure-status` is
38
-
instructing `compiletest` to expect a failure status of 1 (rather than the current Rust default of 101 at the time of this
39
-
writing). The header command and the argument list (if present) are typically separated by a colon:
56
+
57
+
Here is an example, specifying the `must-compile-successfully` header command,
58
+
which takes no arguments, followed by the `failure-status` header command,
59
+
which takes a single argument (which, in this case is a value of 1).
60
+
`failure-status` is instructing `compiletest` to expect a failure status of 1
61
+
(rather than the current Rust default of 101 at the time of this writing). The
62
+
header command and the argument list (if present) are typically separated by a
63
+
colon:
40
64
```
41
65
// Copyright 2018 The Rust Project Developers. See the COPYRIGHT
42
66
// file at the top-level directory of this distribution and at
One would add a new header command if there is a need to define some test property or behavior on an individual, test-by-test
65
-
basis. A header command property serves as the header command's backing store (holds the command's current value) at
66
-
runtime.
88
+
89
+
One would add a new header command if there is a need to define some test
90
+
property or behavior on an individual, test-by-test basis. A header command
91
+
property serves as the header command's backing store (holds the command's
92
+
current value) at runtime.
67
93
68
94
To add a new header command property:
69
-
1. Look for the `pub struct TestProps` declaration in [src/tools/compiletest/src/header.rs](https://github.com/rust-lang/rust/tree/master/src/tools/compiletest/src/header.rs) and add
70
-
the new public property to the end of the declaration.
71
-
2. Look for the `impl TestProps` implementation block immediately following the struct declaration and initialize the new
72
-
property to its default value.
95
+
1. Look for the `pub struct TestProps` declaration in
96
+
[src/tools/compiletest/src/header.rs][header] and add the new public
97
+
property to the end of the declaration.
98
+
2. Look for the `impl TestProps` implementation block immediately following
99
+
the struct declaration and initialize the new property to its default
100
+
value.
73
101
74
102
#### Adding a new header command parser
75
-
When `compiletest` encounters a test file, it parses the file a line at a time by calling every parser defined in the
76
-
`Config` struct's implementation block, also in [src/tools/compiletest/src/header.rs](https://github.com/rust-lang/rust/tree/master/src/tools/compiletest/src/header.rs) (note the `Config` struct's declaration
77
-
block is found in [src/tools/compiletest/src/common.rs](https://github.com/rust-lang/rust/tree/master/src/tools/compiletest/src/common.rs). `TestProps`'s `load_from()` method will try passing the current
78
-
line of text to each parser, which, in turn typically checks to see if the line begins with a particular commented (`//`)
79
-
header command such as `// must-compile-successfully` or `// failure-status`. Whitespace after the comment marker is
80
-
optional.
81
-
82
-
Parsers will override a given header command property's default value merely by being specified in the test file as a header
83
-
command or by having a parameter value specified in the test file, depending on the header command.
84
-
85
-
Parsers defined in `impl Config` are typically named `parse_<header_command>` (note kebab-case `<header-command>` transformed
86
-
to snake-case `<header_command>`). `impl Config` also defines several 'low-level' parsers which make it simple to parse
87
-
common patterns like simple presence or not (`parse_name_directive()`), header-command:parameter(s)
88
-
(`parse_name_value_directive()`), optional parsing only if a particular `cfg` attribute is defined (`has_cfg_prefix()`) and
89
-
many more. The low-level parsers are found near the end of the `impl Config` block; be sure to look through them and their
90
-
associated parsers immediately above to see how they are used to avoid writing additional parsing code unneccessarily.
91
-
92
-
As a concrete example, here is the implementation for the `parse_failure_status()` parser, in
As a concrete example, here is the implementation for the
130
+
`parse_failure_status()` parser, in
131
+
[src/tools/compiletest/src/header.rs][header]:
132
+
94
133
```diff
95
134
@@ -232,6 +232,7 @@ pub struct TestProps {
96
135
// customized normalization rules
@@ -132,14 +171,21 @@ As a concrete example, here is the implementation for the `parse_failure_status(
132
171
```
133
172
134
173
## Implementing the behavior change
135
-
When a test invokes a particular header command, it is expected that some behavior will change as a result. What behavior,
136
-
obviously, will depend on the purpose of the header command. In the case of `failure-status`, the behavior that changes
137
-
is that `compiletest` expects the failure code defined by the header command invoked in the test, rather than the default
138
-
value.
139
-
140
-
Although specific to `failure-status` (as every header command will have a different implementation in order to invoke
141
-
behavior change) perhaps it is helpful to see the behavior change implementation of one case, simply as an example. To implement `failure-status`, the `check_correct_failure_status()` function found in the `TestCx` implementation block,
142
-
located in [src/tools/compiletest/src/runtest.rs](https://github.com/rust-lang/rust/tree/master/src/tools/compiletest/src/runtest.rs), was modified as per below:
174
+
175
+
When a test invokes a particular header command, it is expected that some
176
+
behavior will change as a result. What behavior, obviously, will depend on the
177
+
purpose of the header command. In the case of `failure-status`, the behavior
178
+
that changes is that `compiletest` expects the failure code defined by the
179
+
header command invoked in the test, rather than the default value.
180
+
181
+
Although specific to `failure-status` (as every header command will have a
182
+
different implementation in order to invoke behavior change) perhaps it is
183
+
helpful to see the behavior change implementation of one case, simply as an
184
+
example. To implement `failure-status`, the `check_correct_failure_status()`
185
+
function found in the `TestCx` implementation block, located in
0 commit comments