From a30d61b05a7b11bcc52c2d4988c0a5f7fedce2ff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adrien=20T=C3=A9tar?= Date: Sat, 11 Jan 2014 15:19:38 +0100 Subject: [PATCH] Various READMEs and docs cleanup Noticeably closes #11428. --- CONTRIBUTING.md | 2 +- README.md | 51 ++++++++++++++++----------------- doc/README | 28 ------------------ doc/README.md | 40 ++++++++++++++++++++++++++ doc/complement-bugreport.md | 34 +++++++++++----------- doc/complement-lang-faq.md | 2 +- doc/complement-project-faq.md | 2 +- doc/complement-usage-faq.md | 10 ++----- doc/index.md | 54 ++++++++++++++++++----------------- src/README.md | 43 ++++++++++++++++++++++++++++ src/README.txt | 43 ---------------------------- src/libsyntax/diagnostic.rs | 2 +- 12 files changed, 158 insertions(+), 153 deletions(-) delete mode 100644 doc/README create mode 100644 doc/README.md create mode 100644 src/README.md delete mode 100644 src/README.txt diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2684ea2d9a0..52598ea3c69 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 diff --git a/README.md b/README.md index ab6dca6a3a9..207daa61155 100644 --- a/README.md +++ b/README.md @@ -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. - diff --git a/doc/README b/doc/README deleted file mode 100644 index d7578987e2b..00000000000 --- a/doc/README +++ /dev/null @@ -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 diff --git a/doc/README.md b/doc/README.md new file mode 100644 index 00000000000..3942603159b --- /dev/null +++ b/doc/README.md @@ -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 diff --git a/doc/complement-bugreport.md b/doc/complement-bugreport.md index 15f655ac5e3..d84d720871d 100644 --- a/doc/complement-bugreport.md +++ b/doc/complement-bugreport.md @@ -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) diff --git a/doc/complement-lang-faq.md b/doc/complement-lang-faq.md index 6a96a7728de..3572a411e0a 100644 --- a/doc/complement-lang-faq.md +++ b/doc/complement-lang-faq.md @@ -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. diff --git a/doc/complement-project-faq.md b/doc/complement-project-faq.md index 066434cd833..8665644c1f1 100644 --- a/doc/complement-project-faq.md +++ b/doc/complement-project-faq.md @@ -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. diff --git a/doc/complement-usage-faq.md b/doc/complement-usage-faq.md index 42bc979e5f1..aca7d833849 100644 --- a/doc/complement-usage-faq.md +++ b/doc/complement-usage-faq.md @@ -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. diff --git a/doc/index.md b/doc/index.md index 5ee7fccc48c..04682a56e97 100644 --- a/doc/index.md +++ b/doc/index.md @@ -6,44 +6,46 @@ .header-section-number { display: none; } -[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) diff --git a/src/README.md b/src/README.md new file mode 100644 index 00000000000..b3751e56c03 --- /dev/null +++ b/src/README.md @@ -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 | + diff --git a/src/README.txt b/src/README.txt deleted file mode 100644 index 1ee08247c73..00000000000 --- a/src/README.txt +++ /dev/null @@ -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 diff --git a/src/libsyntax/diagnostic.rs b/src/libsyntax/diagnostic.rs index 18479d4ef41..23d0f4585af 100644 --- a/src/libsyntax/diagnostic.rs +++ b/src/libsyntax/diagnostic.rs @@ -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,