nordic-dev.net/rust
nordic-dev.net/rust
2
0
Fork 0
mirror of https://github.com/rust-lang/rust.git synced 2024-11-01 06:51:58 +00:00
Code Issues Packages Projects Releases Wiki Activity

Various READMEs and docs cleanup

Browse Source 
Noticeably closes #11428.
This commit is contained in:
Adrien Tétar 2014-01-11 15:19:38 +01:00
parent 01794cc993
commit a30d61b05a
12 changed files with 158 additions and 153 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
CONTRIBUTING.md
View File

@ -2,7 +2,7 @@
If you're just reporting a bug, please see:
https://github.com/mozilla/rust/wiki/HOWTO-submit-a-Rust-bug-report
http://static.rust-lang.org/doc/master/complement-bugreport.html
## Pull request procedure

51
README.md
View File

@ -7,50 +7,49 @@ documentation.
### Windows
1. Download and use the [installer][win-exe].
1. Download and use the [installer and MinGW][win-wiki].
2. Read the [tutorial].
2. Enjoy!
> ***Note:*** Windows users should read the detailed
> [getting started][wiki-start] notes on the wiki. Even when using
> the binary installer the Windows build requires a MinGW installation,
> the precise details of which are not discussed here.
> ***Note:*** Windows users can read the detailed
> [getting started][wiki-start] notes on the wiki.
[tutorial]: http://static.rust-lang.org/doc/tutorial.html
[wiki-start]: https://github.com/mozilla/rust/wiki/Note-getting-started-developing-Rust
[win-exe]: http://static.rust-lang.org/dist/rust-0.9-install.exe
[win-wiki]: https://github.com/mozilla/rust/wiki/Using-Rust-on-Windows
### Linux / OS X
1. Install the prerequisites (if not already installed)
* g++ 4.4 or clang++ 3.x
* python 2.6 or later (but not 3.x)
* perl 5.0 or later
* gnu make 3.81 or later
* curl
2. Download and build Rust
1. Make sure you have installed the dependencies:
* `g++` 4.4 or `clang++` 3.x
* `python` 2.6 or later (but not 3.x)
* `perl` 5.0 or later
* GNU `make` 3.81 or later
* `curl`
2. Download and build Rust:
You can either download a [tarball] or build directly from the [repo].
To build from the [tarball] do:
$ curl -O http://static.rust-lang.org/dist/rust-0.9.tar.gz
$ tar -xzf rust-0.9.tar.gz
$ cd rust-0.9
Or to build from the [repo] do:
$ git clone https://github.com/mozilla/rust.git
$ cd rust
Now that you have Rust's source code, you can configure and build it:
$ ./configure
$ make && make install
You may need to use `sudo make install` if you do not normally have
permission to modify the destination directory. The install locations can
be adjusted by passing a `--prefix` argument to `configure`. Various other
options are also supported, pass `--help` for more information on them.
> ***Note:*** You may need to use `sudo make install` if you do not normally have
> permission to modify the destination directory. The install locations can
> be adjusted by passing a `--prefix` argument to `configure`. Various other
> options are also supported, pass `--help` for more information on them.
When complete, `make install` will place several programs into
`/usr/local/bin`: `rustc`, the Rust compiler; `rustdoc`, the
@ -76,17 +75,16 @@ Snapshot binaries are currently built and tested on several platforms:
* Linux (various distributions), x86 and x86-64
* OSX 10.6 ("Snow Leopard") or greater, x86 and x86-64
You may find that other platforms work, but these are our "tier 1"
You may find that other platforms work, but these are our officially
supported build environments that are most likely to work.
Rust currently needs about 1.8G of RAM to build without swapping; if it hits
Rust currently needs about 1.5 GiB of RAM to build without swapping; if it hits
swap, it will take a very long time to build.
There is lots more documentation in the [wiki].
There is a lot more documentation in the [wiki].
[wiki]: https://github.com/mozilla/rust/wiki
## License
Rust is primarily distributed under the terms of both the MIT license
@ -94,4 +92,3 @@ and the Apache License (Version 2.0), with portions covered by various
BSD-like licenses.
See LICENSE-APACHE, LICENSE-MIT, and COPYRIGHT for details.

28
doc/README
View File

@ -1,28 +0,0 @@
Pandoc, a universal document converter, is required to generate docs as HTML
from Rust's source code. It's available for most platforms here:
http://johnmacfarlane.net/pandoc/installing.html
Node.js (http://nodejs.org/) is also required for generating HTML from
the Markdown docs (reference manual, tutorials, etc.) distributed with
this git repository.
To generate all the docs, run `make docs` from the root of the repository.
This will convert the distributed Markdown docs to HTML and generate HTML doc
for the 'std' and 'extra' libraries.
To generate HTML documentation from one source file/crate, do something like:
rustdoc --output-dir html-doc/ --output-format html ../src/libstd/path.rs
(This, of course, requires that you've built/installed the `rustdoc` tool.)
To generate an HTML version of a doc from Markdown, without having Node.js
installed, do something like:
pandoc --from=markdown --to=html5 --number-sections -o rust.html rust.md
The syntax for pandoc flavored markdown can be found at:
http://johnmacfarlane.net/pandoc/README.html#pandocs-markdown
A nice quick reference (for non-pandoc markdown) is at:
http://kramdown.rubyforge.org/quickref.html

40
doc/README.md Normal file
View File

@ -0,0 +1,40 @@
# Dependencies
[Pandoc](http://johnmacfarlane.net/pandoc/installing.html), a universal
document converter, is required to generate docs as HTML from Rust's
source code.
[Node.js](http://nodejs.org/) is also required for generating HTML from
the Markdown docs (reference manual, tutorials, etc.) distributed with
this git repository.
# Building
To generate all the docs, just run `make docs` from the root of the repository.
This will convert the distributed Markdown docs to HTML and generate HTML doc
for the 'std' and 'extra' libraries.
To generate HTML documentation from one source file/crate, do something like:
~~~~
rustdoc --output-dir html-doc/ --output-format html ../src/libstd/path.rs
~~~~
(This, of course, requires a working build of the `rustdoc` tool.)
# Additional notes
To generate an HTML version of a doc from Markdown without having Node.js
installed, you can do something like:
~~~~
pandoc --from=markdown --to=html5 --number-sections -o rust.html rust.md
~~~~
(rust.md being the Rust Reference Manual.)
The syntax for pandoc flavored markdown can be found at:
http://johnmacfarlane.net/pandoc/README.html#pandocs-markdown
A nice quick reference (for non-pandoc markdown) is at:
http://kramdown.rubyforge.org/quickref.html

34
doc/complement-bugreport.md
View File

@ -1,47 +1,45 @@
% HOWTO submit a RUST bug report
% How to submit a Rust bug report
# I think I found a bug in the compiler!
If you see this message: ''error: internal compiler error: unexpected failure'',
If you see this message: `error: internal compiler error: unexpected failure`,
then you have definitely found a bug in the compiler. It's also possible that
your code is not well-typed, but if you saw this message, it's still a bug in
error reporting.
If you see a message about an LLVM assertion failure, then you have also
If you see a message about an LLVM assertion failure, then you have also
definitely found a bug in the compiler. In both of these cases, it's not your
fault and you should report a bug!
If you see a compiler error message that you think is meant for users to see,
If you see a compiler error message that you think is meant for users to see,
but it confuses you, *that's a bug too*. If it wasn't clear to you, then it's
an error message we want to improve, so please report it so that we can try
to make it better.
# I don't want to waste the Rust devs' time! How do I know the bug I found isn't a bug that already exists in the issue tracker?
# How do I know the bug I found isn't a bug that already exists in the issue tracker?
If you don't have much time, then don't worry about that. Just submit the bug.
If it's a duplicate, somebody will notice that and close it. No one will laugh
at you, we promise (and if someone did, they would be violating the Rust
[code of conduct](https://github.com/mozilla/rust/wiki/Note-development-policy code of conduct)).
If you don't have enough time for a search, then don't worry about that. Just submit
the bug. If it's a duplicate, somebody will notice that and close it during triage.
If you have more time, it's very helpful if you can type the text of the error
If you have the time for it, it would be useful to type the text of the error
message you got [into the issue tracker search box](https://github.com/mozilla/rust/issues)
to see if there's an existing bug that resembles your problem. If there is,
and it's an open bug, you can comment on that issue and say you ran into it too.
This will encourage devs to fix it. But again, don't let this stop you from
and it's an open bug, you can comment on that issue and say you are also affected.
This will encourage the devs to fix it. But again, don't let this stop you from
submitting a bug. We'd rather have to do the work of closing duplicates than
miss out on valid bug reports.
# What information should I include in a bug report?
It's helpful to include your specific OS (for example: Mac OS X 10.8.3,
Windows 7, Ubuntu 12.0.4) and your hardware architecture (for example: i686, x86_64).
It generally helps our diagnosis to include your specific OS (for example: Mac OS X 10.8.3,
Windows 7, Ubuntu 12.04) and your hardware architecture (for example: i686, x86_64).
It's also helpful to copy/paste the output of re-running the erroneous rustc
commmand with the `-v` flag. Finally, if you can run the offending command under gdb,
pasting a stack trace can be useful; to do so, you will need to set a breakpoint on `rust_begin_unwind`.
command with the `-v` flag. Finally, if you can run the offending command under gdb,
pasting a stack trace can be useful; to do so, you will need to set a breakpoint on `rust_fail`.
# I submitted a bug, but nobody has commented on it! I'm sad.
# I submitted a bug, but nobody has commented on it!
This is sad, but does happen sometimes, since we're short-staffed. If you
This is sad, but does happen sometimes, since we're short-staffed. If you
submit a bug and you haven't received a comment on it within 3 business days,
it's entirely reasonable to either ask on the #rust IRC channel,
or post on the [rust-dev mailing list](https://mail.mozilla.org/listinfo/rust-dev)

2
doc/complement-lang-faq.md
View File

@ -236,7 +236,7 @@ They start small (ideally in the hundreds of bytes) and expand dynamically by ca
* Requiring explicit bounds means that the compiler can type-check the code at the point where the type-parametric item is *defined*, rather than delaying to when its type parameters are instantiated. You know that *any* set of type parameters fulfilling the bounds listed in the API will compile. It's an enforced minimal level of documentation, and results in very clean error messages.
* Scoping of methods is also a problem. C++ needs [Koenig (argument dependent) lookup](http://en.wikipedia.org/wiki/Argument-dependent_name_lookup), which comes with its own host of problems. Explicit bounds avoid this issue: traits are explicitly imported and then used as bounds on type parameters, so there is a clear mapping from the method to its implementation (via the trait and the instantiated type).
* Scoping of methods is also a problem. C++ needs [Koenig (argument dependent) lookup](http://en.wikipedia.org/wiki/Argument-dependent_name_lookup), which comes with its own host of problems. Explicit bounds avoid this issue: traits are explicitly imported and then used as bounds on type parameters, so there is a clear mapping from the method to its implementation (via the trait and the instantiated type).
* Related to the above point: since a parameter explicitly names its trait bounds, a single type is able to implement traits whose sets of method names overlap, cleanly and unambiguously.

2
doc/complement-project-faq.md
View File

@ -15,7 +15,7 @@ Existing languages at this level of abstraction and efficiency are unsatisfactor
# What are some non-goals?
* To employ any particularly cutting-edge technologies. Old, established techniques are better.
* To prize expressiveness, minimalism or elegance above other goals. These are desirable but subordinate goals.
* To prize expressiveness, minimalism or elegance above other goals. These are desirable but subordinate goals.
* To cover the "systems language" part all the way down to "writing an OS kernel".
* To cover the complete feature-set of C++, or any other language. It should provide majority-case features.
* To be 100% static, 100% safe, 100% reflective, or too dogmatic in any other sense. Trade-offs exist.

10
doc/complement-usage-faq.md
View File

@ -20,16 +20,12 @@ If you aren't sure which paths you need, try setting RUST_LOG to `::help` and ru
This is much like the answer for `log` statements, except that you also need to compile your program in debug mode (that is, pass `--cfg debug` to `rustc`). Note that if you want to see the instrumentation of the `debug!` statements within `rustc` itself, you need a debug version of `rustc`; you can get one by invoking `configure` with the `--enable-debug` option.
# What does it mean when a program exits with `leaked memory in rust main loop (2 objects)' failed, rt/memory_region.cpp:99 2 objects`?
# What does it mean when a program exits with `leaked memory`?
The error looks like this: `leaked memory in rust main loop (2 objects)' failed, rt/memory_region.cpp:99 2 objects`.
This message indicates a memory leak, and is mostly likely to happen on rarely exercised failure paths. Note that failure unwinding is not yet implemented on windows so this is expected. If you see this on Linux or Mac it's a compiler bug; please report it.
# Why do gdb backtraces end with the error 'previous frame inner to this frame (corrupt stack?)'?
**Short answer** your gdb is too old to understand our hip new stacks. Upgrade to a newer version (7.3.1 is known to work).
**Long answer** Rust uses 'spaghetti stacks' (a linked list of stacks) to allow tasks to start very small but recurse arbitrarily deep when necessary. As a result, new frames don't always decrease the stack pointer like gdb expects but instead may jump around the heap to different stack segments. Newer versions of gdb recognize that the special function called __morestack may change the stack pointer to a different stack.
# Why did my build create a bunch of zero-length files in my lib directory?
This is a normal part of the Rust build process. The build system uses these zero-length files for dependency tracking, as the actual names of the Rust libraries contain hashes that can't be guessed easily by the Makefiles.

54
doc/index.md
View File

@ -6,44 +6,46 @@
.header-section-number { display: none; }
</style>
[The Rust tutorial](tutorial.html)
[The Rust reference manual](rust.html) ([PDF](rust.pdf))
[The Rust tutorial](tutorial.html) ([PDF](tutorial.pdf))
[The Rust reference manual](rust.html) ([PDF](rust.pdf))
# Guides
[Pointers](guide-pointers.html)
[References and Lifetimes](guide-lifetimes.html)
[Containers and Iterators](guide-container.html)
[Tasks and Communication](guide-tasks.html)
[Foreign Function Interface](guide-ffi.html)
[Macros](guide-macros.html)
[Packaging](guide-rustpkg.html)
[Testing](guide-testing.html)
[Conditions](guide-conditions.html)
[Pointers](guide-pointers.html)
[References and Lifetimes](guide-lifetimes.html)
[Containers and Iterators](guide-container.html)
[Tasks and Communication](guide-tasks.html)
[Foreign Function Interface](guide-ffi.html)
[Macros](guide-macros.html)
[Packaging](guide-rustpkg.html)
[Testing](guide-testing.html)
[Conditions](guide-conditions.html)
# Libraries
[std](std/index.html)
[extra](extra/index.html)
[green](green/index.html)
[native](native/index.html)
[syntax](syntax/index.html)
[rustc](rustc/index.html)
[The standard library, `libstd`](std/index.html)
[The extra library, `libextra`](extra/index.html)
[The M:N runtime library, `libgreen`](green/index.html)
[The 1:1 runtime library, `libnative`](native/index.html)
[The Rust parser, `libsyntax`](syntax/index.html)
[The Rust compiler, `librustc`](rustc/index.html)
# Tooling
[The rustpkg manual](rustpkg.html)
[The `rustpkg` manual](rustpkg.html)
# FAQs
[Language FAQ](complement-lang-faq.html)
[Project FAQ](complement-project-faq.html)
[Usage FAQ](complement-usage-faq.html)
[Code cheatsheet](complement-cheatsheet.html) - "How do I do X?"
[HOWTO submit a bug report](complement-bugreport.html)
[Language FAQ](complement-lang-faq.html)
[Project FAQ](complement-project-faq.html)
[Usage FAQ](complement-usage-faq.html)
[Code cheatsheet](complement-cheatsheet.html) - "How do I do X?"
[How to submit a bug report](complement-bugreport.html)
# External resources
The Rust [IRC channel](http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust) - #rust on irc.mozilla.org
The Rust community on [Reddit](http://reddit.com/r/rust)
The Rust [wiki](http://github.com/mozilla/rust/wiki)
The Rust [IRC channel](http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust) - `#rust` on irc.mozilla.org
The Rust community on [Reddit](http://reddit.com/r/rust)
The Rust [wiki](http://github.com/mozilla/rust/wiki)

43
src/README.md Normal file
View File

@ -0,0 +1,43 @@
This is a preliminary version of the Rust compiler, libraries and tools.
Source layout:
| `librustc/` | The self-hosted compiler |
| `libstd/` | The standard library (imported and linked by default) |
| `libextra/` | The "extras" library (slightly more peripheral code) |
| `libsyntax/` | The Rust parser and pretty-printer |
| ------------------- | --------------------------------------------------------- |
| `rt/` | The runtime system |
| `rt/rust_*.c` | - The majority of the runtime services |
| `rt/isaac` | - The PRNG used for pseudo-random choices in the runtime |
| `rt/bigint` | - The bigint library used for the 'big' type |
| `rt/uthash` | - Small hashtable-and-list library for C, used in runtime |
| `rt/sync` | - Concurrency utils |
| `rt/util` | - Small utility classes for the runtime. |
| `rt/vg` | - Valgrind headers |
| `rt/msvc` | - MSVC support |
| ------------------- | --------------------------------------------------------- |
| `test/` | Testsuite |
| `test/compile-fail` | - Tests that should fail to compile |
| `test/run-fail` | - Tests that should compile, run and fail |
| `test/run-pass` | - Tests that should compile, run and succeed |
| `test/bench` | - Benchmarks and miscellaneous |
| `test/pretty` | - Pretty-printer tests |
| `test/auxiliary` | - Dependencies of tests |
| ------------------- | --------------------------------------------------------- |
| `compiletest/` | The test runner |
| ------------------- | --------------------------------------------------------- |
| `librustpkg/` | The package manager and build system |
| ------------------- | --------------------------------------------------------- |
| `librustdoc/` | The Rust API documentation tool |
| ------------------- | --------------------------------------------------------- |
| `llvm/` | The LLVM submodule |
| ------------------- | --------------------------------------------------------- |
| `libuv/` | The libuv submodule |
| ------------------- | --------------------------------------------------------- |
| `rustllvm/` | LLVM support code |
| ------------------- | --------------------------------------------------------- |
| `libfuzzer/` | A collection of fuzz testers |
| ------------------- | --------------------------------------------------------- |
| `etc/` | Scripts, editors support, misc |

43
src/README.txt
View File

@ -1,43 +0,0 @@
This is a preliminary version of the Rust compiler, libraries and tools
Source layout:
librustc/ The self-hosted compiler
libstd/ The standard library (imported and linked by default)
libextra/ The "extras" library (slightly more peripheral code)
libsyntax/ The Rust parser and pretty-printer
rt/ The runtime system
rt/rust_*.cpp - The majority of the runtime services
rt/isaac - The PRNG used for pseudo-random choices in the runtime
rt/bigint - The bigint library used for the 'big' type
rt/uthash - Small hashtable-and-list library for C, used in runtime
rt/sync - Concurrency utils
rt/util - Small utility classes for the runtime.
rt/vg - Valgrind headers
rt/msvc - MSVC support
test/ Testsuite
test/compile-fail - Tests that should fail to compile
test/run-fail - Tests that should compile, run and fail
test/run-pass - Tests that should compile, run and succeed
test/bench - Benchmarks and miscellanea
test/pretty - Pretty-printer tests
test/auxiliary - Dependencies of tests
compiletest/ The test runner
librustpkg/ The package manager and build system
librustdoc/ The Rust API documentation tool
llvm/ The LLVM submodule
libuv/ The libuv submodule
rustllvm/ LLVM support code
libfuzzer/ A collection of fuzz testers
etc/ Scripts, editor support, misc

2
src/libsyntax/diagnostic.rs
View File

@ -18,7 +18,7 @@ use std::local_data;
use extra::term;
static BUG_REPORT_URL: &'static str =
"https://github.com/mozilla/rust/wiki/HOWTO-submit-a-Rust-bug-report";
"http://static.rust-lang.org/doc/master/complement-bugreport.html";
pub trait Emitter {
fn emit(&self,