Auto merge of #28366 - christopherdumas:beginners_manuel, r=steveklabnik

This is something that I wish I had when I started contributing to Rust (not that long ago :). I plan on writing a manual for bors and the rust testing setup too, if there isn't one already.
This commit is contained in:
bors 2015-09-12 22:15:41 +00:00
commit f710aae2ef
2 changed files with 67 additions and 0 deletions

43
COMPILER_TESTS.md Normal file
View File

@ -0,0 +1,43 @@
# Compiler Test Documentation
In the Rust project, we use a special set of comands imbedded in
comments to test the Rust compiler. There are two groups of commands:
1. Header commands
2. Error info commands
Both types of commands are inside comments, but header commands should
be in a comment before any code.
## Summary of Error Info Commands
Error commands specify something about certain lines of the
program. They tell the test what kind of error and what message you
are expecting.
* `~`: Associates the following error level and message with the
current line
* `~|`: Associates the following error level and message with the same
line as the previous comment
* `~^`: Associates the following error level and message with the
previous line. Each caret (`^`) that you add adds a line to this, so
`~^^^^^^^` is seven lines up.
The error levels that you can have are:
1. `ERROR`
2. `WARNING`
3. `NOTE`
4. `HELP` and `SUGGESTION`*
\* **Note**: `SUGGESTION` must follow emediatly after `HELP`.
## Summary of Header Commands
Header commands specify something about the entire test file, as a
whole, instead of just a few lines inside the test.
* `ignore-X` where `X` is an architecture, OS or stage will ignore the test accordingly
* `ignore-pretty` will not compile the pretty-printed test (this is done to test the pretty-printer, but might not always work)
* `ignore-test` always ignores the test
* `ignore-lldb` and `ignore-gdb` will skip the debuginfo tests
* `min-{gdb,lldb}-version`

View File

@ -10,6 +10,7 @@ links to the major sections:
* [Writing Documentation](#writing-documentation)
* [Issue Triage](#issue-triage)
* [Out-of-tree Contributions](#out-of-tree-contributions)
* [Helpful Links and Information](#helpful-links-and-information)
If you have questions, please make a post on [internals.rust-lang.org][internals] or
hop on [#rust-internals][pound-rust-internals].
@ -210,3 +211,26 @@ valuable!
[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
## Helpful Links and Information
For people new to Rust, and just starting to contribute, or even for
more seasoned developers, some useful places to look for information
are:
* The [Rust Internals forum][rif], a place to ask questions and
discuss Rust's internals
* The [generated documentation for rust's compiler][gdfrustc]
* The [rust referance][rr], even though it doesn't specifically talk about Rust's internals, its a great reasource nontheless
* Although out of date, [Tom Lee's great blog article][tlgba] is very helpful
* [rustaceans.org][ro] is helpful, but mostly dedicated to IRC
* The [Rust Compiler Testing Docs][rctd]
* **Google**!
* Don't be afraid to ask! The Rust community is friendly and helpful.
[gdfrustc]: http://manishearth.github.io/rust-internals-docs/rustc/
[rif]: http://internals.rust-lang.org
[rr]: https://doc.rust-lang.org/book/README.html
[tlgba]: http://tomlee.co/2014/04/03/a-more-detailed-tour-of-the-rust-compiler/
[ro]: http://www.rustaceans.org/
[rctd]: ./COMPILER_TESTS.md