--- /dev/null
+% HOWTO 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'',
+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
+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,
+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?
+
+ 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 have more time, it's very helpful if you can 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
+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'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`.
+
+# I submitted a bug, but nobody has commented on it! I'm sad.
+
+ 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)
+to ask what the status of the bug is.
--- /dev/null
+% Rust Cheatsheet
+
+# How do I convert *X* to *Y*?
+
+**Int to string**
+
+Use [`ToStr`](http://static.rust-lang.org/doc/master/std/to_str/trait.ToStr.html).
+
+```rust
+let x: int = 42;
+let y: ~str = x.to_str();
+```
+
+**String to int**
+
+Use [`FromStr`](http://static.rust-lang.org/doc/master/std/from_str/trait.FromStr.html), and its helper function, [`from_str`](http://static.rust-lang.org/doc/master/std/from_str/fn.from_str.html).
+
+```rust
+let x: Option<int> = from_str("42");
+let y: int = x.unwrap();
+```
+
+**Int to string, in non-base-10**
+
+Use [`ToStrRadix`](http://static.rust-lang.org/doc/master/std/num/trait.ToStrRadix.html).
+
+```rust
+use std::num::ToStrRadix;
+
+let x: int = 42;
+let y: ~str = x.to_str_radix(16);
+```
+
+**String to int, in non-base-10**
+
+Use [`FromStrRadix`](http://static.rust-lang.org/doc/master/std/num/trait.FromStrRadix.html), and its helper function, [`from_str_radix`](http://static.rust-lang.org/doc/master/std/num/fn.from_str_radix.html).
+
+```rust
+use std::num::from_str_radix;
+
+let x: Option<int> = from_str_radix("deadbeef", 16);
+let y: int = x.unwrap();
+```
+
+# File operations
+
+## How do I read from a file?
+
+Use [`File::open`](http://static.rust-lang.org/doc/master/std/io/fs/struct.File.html#method.open) to create a [`File`](http://static.rust-lang.org/doc/master/std/io/fs/struct.File.html) struct, which implements the [`Reader`](http://static.rust-lang.org/doc/master/std/io/trait.Reader.html) trait.
+
+```rust
+use std::path::Path;
+use std::io::fs::File;
+
+let path : Path = Path::new("Doc-FAQ-Cheatsheet.md");
+let on_error = || fail!("open of {:?} failed", path);
+let reader : File = File::open(&path).unwrap_or_else(on_error);
+```
+
+## How do I iterate over the lines in a file?
+
+Use the [`lines`](http://static.rust-lang.org/doc/master/std/io/trait.Buffer.html#method.lines) method on a [`BufferedReader`](http://static.rust-lang.org/doc/master/std/io/buffered/struct.BufferedReader.html).
+
+```rust
+use std::io::buffered::BufferedReader;
+
+let mut reader = BufferedReader::new(reader);
+for line in reader.lines() {
+ print!("line: {}", line);
+}
+```
+
+# String operations
+
+## How do I search for a substring?
+
+Use the [`find_str`](http://static.rust-lang.org/doc/master/std/str/trait.StrSlice.html#tymethod.find_str) method.
+
+```rust
+let str = "Hello, this is some random string";
+let index: Option<uint> = str.find_str("rand");
+```
+
+# Containers
+
+## How do I get the length of a vector?
+
+The [`Container`](http://static.rust-lang.org/doc/master/std/container/trait.Container.html) trait provides the `len` method.
+
+```rust
+let u: ~[u32] = ~[0, 1, 2];
+let v: &[u32] = &[0, 1, 2, 3];
+let w: [u32, .. 5] = [0, 1, 2, 3, 4];
+
+println!("u: {}, v: {}, w: {}", u.len(), v.len(), w.len()); // 3, 4, 5
+```
+
+## How do I iterate over a vector?
+
+Use the [`iter`](http://static.rust-lang.org/doc/master/std/vec/trait.ImmutableVector.html#tymethod.iter) method.
+
+```rust
+let values: ~[int] = ~[1, 2, 3, 4, 5];
+for value in values.iter() { // value: &int
+ println!("{}", *value);
+}
+```
+
+(See also [`mut_iter`](http://static.rust-lang.org/doc/master/std/vec/trait.MutableVector.html#tymethod.mut_iter) which yields `&mut int` and [`move_iter`](http://static.rust-lang.org/doc/master/std/vec/trait.OwnedVector.html#tymethod.move_iter) which yields `int` while consuming the `values` vector.)
+
+# Type system
+
+## How do I store a function in a struct?
+
+```rust
+struct Foo {
+ myfunc: fn(int, uint) -> i32
+}
+
+struct FooClosure<'a> {
+ myfunc: 'a |int, uint| -> i32
+}
+
+fn a(a: int, b: uint) -> i32 {
+ (a as uint + b) as i32
+}
+
+fn main() {
+ let f = Foo { myfunc: a };
+ let g = FooClosure { myfunc: |a, b| { (a - b as int) as i32 } };
+ println!("{}", (f.myfunc)(1, 2));
+ println!("{}", (g.myfunc)(3, 4));
+}
+```
+
+Note that the parenthesis surrounding `f.myfunc` are necessary: they are how Rust disambiguates field lookup and method call. The `'a` on `FooClosure` is the lifetime of the closure's environment pointer.
+
+## How do I express phantom types?
+
+[Phantom types](http://www.haskell.org/haskellwiki/Phantom_type) are those that cannot be constructed at compile time. To express these in Rust, zero-variant `enum`s can be used:
+
+```rust
+enum Open {}
+enum Closed {}
+```
+
+Phantom types are useful for enforcing state at compile time. For example:
+
+```rust
+struct Door<State>(~str);
+
+fn close(Door(name): Door<Open>) -> Door<Closed> {
+ Door::<Closed>(name)
+}
+
+fn open(Door(name): Door<Closed>) -> Door<Open> {
+ Door::<Open>(name)
+}
+
+let _ = close(Door::<Open>(~"front")); // ok
+let _ = close(Door::<Closed>(~"front")); // error: mismatched types: expected `main::Door<main::Open>` but found `main::Door<main::Closed>`
+```
+
+# FFI (Foreign Function Interface)
+
+## C function signature conversions
+
+Description | C signature | Equivalent Rust signature
+----------------------|----------------------------------------------|------------------------------------------
+no parameters | `void foo(void);` | `fn foo();`
+return value | `int foo(void);` | `fn foo() -> c_int;`
+function parameters | `void foo(int x, int y);` | `fn foo(x: int, y: int);`
+in-out pointers | `void foo(const int* in_ptr, int* out_ptr);` | `fn foo(in_ptr: *c_int, out_ptr: *mut c_int);`
+
+Note: The Rust signatures should be wrapped in an `extern "ABI" { ... }` block.
+
+### Representing opaque handles
+
+You might see things like this in C APIs:
+
+```c
+typedef struct Window Window;
+Window* createWindow(int width, int height);
+```
+
+You can use a zero-element `enum` ([phantom type](#how-do-i-express-phantom-types)) to represent the opaque object handle. The FFI would look like this:
+
+```rust
+enum Window {}
+extern "C" {
+ fn createWindow(width: c_int, height: c_int) -> *Window;
+}
+```
+
+Using a phantom type ensures that the handles cannot be (safely) constructed in client code.
+
+# Contributing to this page
+
+For small examples, have full type annotations, as much as is reasonable, to keep it clear what, exactly, everything is doing. Try to link to the API docs, as well.
+
+Similar documents for other programming languages:
+
+ * [http://pleac.sourceforge.net/](http://pleac.sourceforge.net)
--- /dev/null
+% Language FAQ
+
+# General language issues
+
+## Safety oriented
+
+* Memory safe: no null pointers, dangling pointers, use-before-initialize or use-after-move
+* Expressive mutability control. Immutable by default, statically verified freezing for Owned types
+* No shared mutable state across tasks
+* Dynamic execution safety: task failure / unwinding, trapping, RAII / dtors
+* Safe interior pointer types with lifetime analysis
+
+## Concurrency and efficiency oriented
+
+* Lightweight tasks (coroutines) with expanding stacks
+* Fast asynchronous, copyless message passing
+* Optional garbage collected pointers
+* All types may be explicitly allocated on the stack or interior to other types
+* Static, native compilation using LLVM
+* Direct and simple interface to C code
+
+## Practicality oriented
+
+* Multi-paradigm: pure-functional, concurrent-actor, imperative-procedural, OO
+ * First-class functions, cheap non-escaping closures
+ * Algebraic data types (called enums) with pattern matching
+ * Method implementations on any type
+ * Traits, which share aspects of type classes and interfaces
+* Multi-platform. Developed on Windows, Linux, OS X
+* UTF-8 strings, assortment of machine-level types
+* Works with existing native toolchains, GDB, Valgrind, Instruments, etc
+* Rule-breaking is allowed if explicit about where and how
+
+## What does it look like?
+
+The syntax is still evolving, but here's a snippet from the hash map in core::hashmap.
+
+~~~
+struct LinearMap<K,V> {
+ k0: u64,
+ k1: u64,
+ resize_at: uint,
+ size: uint,
+ buckets: ~[Option<Bucket<K,V>>],
+}
+
+enum SearchResult {
+ FoundEntry(uint), FoundHole(uint), TableFull
+}
+
+fn linear_map_with_capacity<K:Eq + Hash,V>(capacity: uint) -> LinearMap<K,V> {
+ let r = rand::Rng();
+ linear_map_with_capacity_and_keys(r.gen_u64(), r.gen_u64(), capacity)
+}
+
+impl<K:Hash + IterBytes + Eq, V> LinearMap<K,V> {
+
+ fn contains_key(&self, k: &K) -> bool {
+ match self.bucket_for_key(self.buckets, k) {
+ FoundEntry(_) => true,
+ TableFull | FoundHole(_) => false
+ }
+ }
+
+ fn clear(&mut self) {
+ for bkt in self.buckets.mut_iter() {
+ *bkt = None;
+ }
+ self.size = 0;
+ }
+
+...
+}
+~~~
+
+## Are there any big programs written in it yet? I want to read big samples.
+
+There aren't many large programs yet. The Rust [compiler][rustc], 60,000+ lines at the time of writing, is written in Rust. As the oldest body of Rust code it has gone through many iterations of the language, and some parts are nicer to look at than others. It may not be the best code to learn from, but [borrowck] and [resolve] were written recently.
+
+[rustc]: https://github.com/mozilla/rust/tree/master/src/librustc
+[resolve]: https://github.com/mozilla/rust/blob/master/src/librustc/middle/resolve.rs
+[borrowck]: https://github.com/mozilla/rust/blob/master/src/librustc/middle/borrowck/
+
+A research browser engine called [Servo][servo], currently 30,000+ lines across more than a dozen crates, will be exercising a lot of Rust's distinctive type-system and concurrency features, and integrating many native libraries.
+
+[servo]: https://github.com/mozilla/servo
+
+Some examples that demonstrate different aspects of the language:
+
+* [sprocketnes], an NES emulator with no GC, using modern Rust conventions
+* The language's general-purpose [hash] function, SipHash-2-4. Bit twiddling, OO, macros
+* The standard library's [HashMap], a sendable hash map in an OO style
+* The extra library's [json] module. Enums and pattern matching
+
+[sprocketnes]: https://github.com/pcwalton/sprocketnes
+[hash]: https://github.com/mozilla/rust/blob/master/src/libstd/hash.rs
+[HashMap]: https://github.com/mozilla/rust/blob/master/src/libstd/hashmap.rs
+[json]: https://github.com/mozilla/rust/blob/master/src/libextra/json.rs
+
+You may also be interested in browsing [GitHub's Rust][github-rust] page.
+
+[github-rust]: https://github.com/languages/Rust
+
+## Does it run on Windows?
+
+Yes. All development happens in lock-step on all 3 target platforms. Using MinGW, not Cygwin. Note that the windows implementation currently has some limitations: in particular tasks [cannot unwind on windows][unwind], and all Rust executables [require a MinGW installation at runtime][libgcc].
+
+[unwind]: https://github.com/mozilla/rust/issues/908
+[libgcc]: https://github.com/mozilla/rust/issues/1603
+
+## Have you seen this Google language, Go? How does Rust compare?
+
+Rust and Go have similar syntax and task models, but they have very different type systems. Rust is distinguished by greater type safety and memory safety guarantees, more control over memory layout, and robust generics.
+
+Rust has several key features that aren't shared by Go:
+
+* No shared mutable state - Shared mutable state allows data races, a large class of bad bugs. In Rust there is no sharing of mutable data, but ownership of data can be efficiently transferred between tasks.
+* Minimal GC impact - By not having shared mutable data, Rust can avoid global GC, hence Rust never stops the world to collect garbage. With multiple allocation options, individual tasks can completely avoid GC.
+* No null pointers - Accidentally dereferencing null pointers is a big bummer, so Rust doesn't have them.
+* Type parametric code - Generics prove useful time and again, though they are inevitably complex to greater or lesser degrees.
+
+Some of Rust's advantages come at the cost of a more intricate type system than Go's.
+
+Go has its own strengths and in particular has a great user experience that Rust still lacks.
+
+## I like the language but it really needs _$somefeature_.
+
+At this point we are focusing on removing and stabilizing features rather than adding them. File a bug if you think it's important in terms of meeting the existing goals or making the language passably usable. Reductions are more interesting than additions, though.
+
+# Specific language issues
+
+## Is it OO? How do I do this thing I normally do in an OO language?
+
+It is multi-paradigm. Not everything is shoe-horned into a single abstraction. Many things you can do in OO languages you can do in Rust, but not everything, and not always using the same abstraction you're accustomed to.
+
+## How do you get away with "no null pointers"?
+
+Data values in the language can only be constructed through a fixed set of initializer forms. Each of those forms requires that its inputs already be initialized. A liveness analysis ensures that local variables are initialized before use.
+
+## What is the relationship between a module and a crate?
+
+* A crate is a top-level compilation unit that corresponds to a single loadable object.
+* A module is a (possibly nested) unit of name-management inside a crate.
+* A crate contains an implicit, un-named top-level module.
+* Recursive definitions can span modules, but not crates.
+* Crates do not have global names, only a set of non-unique metadata tags.
+* There is no global inter-crate namespace; all name management occurs within a crate.
+ * Using another crate binds the root of _its_ namespace into the user's namespace.
+
+## Why is failure unwinding non-recoverable within a task? Why not try to "catch exceptions"?
+
+In short, because too few guarantees could be made about the dynamic environment of the catch block, as well as invariants holding in the unwound heap, to be able to safely resume; we believe that other methods of signalling and logging errors are more appropriate, with tasks playing the role of a "hard" isolation boundary between separate heaps.
+
+Rust provides, instead, three predictable and well-defined options for handling any combination of the three main categories of "catch" logic:
+
+* Failure _logging_ is done by the integrated logging subsystem.
+* _Recovery_ after a failure is done by trapping a task failure from _outside_ the task, where other tasks are known to be unaffected.
+* _Cleanup_ of resources is done by RAII-style objects with destructors.
+
+Cleanup through RAII-style destructors is more likely to work than in catch blocks anyways, since it will be better tested (part of the non-error control paths, so executed all the time).
+
+## Why aren't modules type-parametric?
+
+We want to maintain the option to parametrize at runtime. We may make eventually change this limitation, but initially this is how type parameters were implemented.
+
+## Why aren't values type-parametric? Why only items?
+
+Doing so would make type inference much more complex, and require the implementation strategy of runtime parametrization.
+
+## Why are enumerations nominal and closed?
+
+We don't know if there's an obvious, easy, efficient, stock-textbook way of supporting open or structural disjoint unions. We prefer to stick to language features that have an obvious and well-explored semantics.
+
+## Why aren't channels synchronous?
+
+There's a lot of debate on this topic; it's easy to find a proponent of default-sync or default-async communication, and there are good reasons for either. Our choice rests on the following arguments:
+
+* Part of the point of isolating tasks is to decouple tasks from one another, such that assumptions in one task do not cause undue constraints (or bugs, if violated!) in another. Temporal coupling is as real as any other kind; async-by-default relaxes the default case to only _causal_ coupling.
+* Default-async supports buffering and batching communication, reducing the frequency and severity of task-switching and inter-task / inter-domain synchronization.
+* Default-async with transmittable channels is the lowest-level building block on which more-complex synchronization topologies and strategies can be built; it is not clear to us that the majority of cases fit the 2-party full-synchronization pattern rather than some more complex multi-party or multi-stage scenario. We did not want to force all programs to pay for wiring the former assumption into all communications.
+
+## Why are channels half-duplex (one-way)?
+
+Similar to the reasoning about default-sync: it wires fewer assumptions into the implementation, that would have to be paid by all use-cases even if they actually require a more complex communication topology.
+
+## Why are strings UTF-8 by default? Why not UCS2 or UCS4?
+
+The `str` type is UTF-8 because we observe more text in the wild in this encoding -- particularly in network transmissions, which are endian-agnostic -- and we think it's best that the default treatment of I/O not involve having to recode codepoints in each direction.
+
+This does mean that indexed access to a Unicode codepoint inside a `str` value is an O(n) operation. On the one hand, this is clearly undesirable; on the other hand, this problem is full of trade-offs and we'd like to point a few important qualifications:
+
+* Scanning a `str` for ASCII-range codepoints can still be done safely octet-at-a-time, with each indexing operation pulling out a `u8` costing only O(1) and producing a value that can be cast and compared to an ASCII-range `char`. So if you're (say) line-breaking on `'\n'`, octet-based treatment still works. UTF8 was well-designed this way.
+* Most "character oriented" operations on text only work under very restricted language assumptions sets such as "ASCII-range codepoints only". Outside ASCII-range, you tend to have to use a complex (non-constant-time) algorithm for determining linguistic-unit (glyph, word, paragraph) boundaries anyways. We recommend using an "honest" linguistically-aware, Unicode-approved algorithm.
+* The `char` type is UCS4. If you honestly need to do a codepoint-at-a-time algorithm, it's trivial to write a `type wstr = [char]`, and unpack a `str` into it in a single pass, then work with the `wstr`. In other words: the fact that the language is not "decoding to UCS4 by default" shouldn't stop you from decoding (or re-encoding any other way) if you need to work with that encoding.
+
+## Why are strings, vectors etc. built-in types rather than (say) special kinds of trait/impl?
+
+In each case there is one or more operator, literal constructor, overloaded use or integration with a built-in control structure that makes us think it would be awkward to phrase the type in terms of more-general type constructors. Same as, say, with numbers! But this is partly an aesthetic call, and we'd be willing to look at a worked-out proposal for eliminating or rephrasing these special cases.
+
+## Can Rust code call C code?
+
+Yes. Since C code typically expects a larger stack than Rust code does, the stack may grow before the call. The Rust domain owning the task that makes the call will block for the duration of the call, so if the call is likely to be long-lasting, you should consider putting the task in its own domain (thread or process).
+
+## Can C code call Rust code?
+
+Yes. The Rust code has to be exposed via an `extern` declaration, which makes it C-ABI compatible. Its address can then be taken and passed to C code. When C calls Rust back, the callback occurs in very restricted circumstances.
+
+## How do Rust's task stacks work?
+
+They start small (ideally in the hundreds of bytes) and expand dynamically by calling through special frames that allocate new stack segments. This is known as the "spaghetti stack" approach.
+
+## What is the difference between a managed box pointer (`@`) and an owned box pointer (`~`)?
+
+* Managed boxes live in the garbage collected task-local heap
+* Owned boxes live in the global exchange heap
+* Managed boxes may be referred to by multiple managed box references
+* Owned boxes have unique ownership and there may only be a single unique pointer to a unique box at a time
+* Managed boxes may not be shared between tasks
+* Owned boxes may be transferred (moved) between tasks
+
+## What is the difference between a borrowed pointer (`&`) and managed and owned boxes?
+
+* Borrowed pointers point to the interior of a stack _or_ heap allocation
+* Borrowed pointers can only be formed when it will provably be outlived by the referent
+* Borrowed pointers to managed box pointers keep the managed boxes alive
+* Borrowed pointers to owned boxes prevent their ownership from being transferred
+* Borrowed pointers employ region-based alias analysis to ensure correctness
+
+## Why aren't function signatures inferred? Why only local slots?
+
+* Mechanically, it simplifies the inference algorithm; inference only requires looking at one function at a time.
+* The same simplification goes double for human readers. A reader does not need an IDE running an inference algorithm across an entire crate to be able to guess at a function's argument types; it's always explicit and nearby.
+* Parameters in Rust can be passed by reference or by value. We can't automatically infer which one the programmer means.
+
+## Why does a type parameter need explicit trait bounds to invoke methods on it, when C++ templates do not?
+
+* 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).
+
+ * 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.
+
+* There is further discussion on [this thread on the Rust mailing list](https://mail.mozilla.org/pipermail/rust-dev/2013-September/005603.html).
+
+## Will Rust implement automatic semicolon insertion, like in Go?
+
+For simplicity, we do not plan to do so. Implementing automatic semicolon insertion for Rust would be tricky because the absence of a trailing semicolon means "return a value".
--- /dev/null
+% Project FAQ
+
+# What is this project's goal, in one sentence?
+
+To design and implement a safe, concurrent, practical, static systems language.
+
+# Why are you doing this?
+
+Existing languages at this level of abstraction and efficiency are unsatisfactory. In particular:
+
+* Too little attention paid to safety.
+* Poor concurrency support.
+* Lack of practical affordances, too dogmatic about paradigm.
+
+# 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 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.
+* To run on "every possible platform". It must eventually work without unnecessary compromises on widely-used hardware and software platforms.
+
+# Is any part of this thing production-ready?
+
+No. Feel free to play around, but don't expect completeness or stability yet. Expect incompleteness and breakage.
+
+What exists presently is:
+
+* A self-hosted (written in Rust) compiler, which uses LLVM as a backend.
+* A runtime library.
+* An evolving standard library.
+* Documentation for the language and libraries.
+* Incomplete tools for packaging and documentation.
+* A test suite covering the compiler and libraries.
+
+# Is this a completely Mozilla-planned and orchestrated thing?
+
+No. It started as a part-time side project in 2006 and remained so for over 3 years. Mozilla got involved in 2009 once the language was mature enough to run some basic tests and demonstrate the idea.
+
+# Why did you do so much work in private?
+
+* A certain amount of shyness. Language work is somewhat political and flame-inducing.
+* Languages designed by committee have a poor track record. Design coherence is important. There were a lot of details to work out and the initial developer (Graydon) had this full time job thing eating up most days.
+
+# Why publish it now?
+
+* The design is stable enough. All the major pieces have reached non-imaginary, initial implementation status. It seems to hold together ok.
+* Languages solely implemented and supported by one person _also_ have a poor track record. To survive it'll need help.
+
+# What will Mozilla use Rust for?
+
+Mozilla intends to use Rust as a platform for prototyping experimental browser architectures. Specifically, the hope is to develop a browser that is more amenable to parallelization than existing ones, while also being less prone to common C++ coding errors. The name of that project is _[Servo](http://github.com/mozilla/servo)_.
+
+# Are you going to use this to suddenly rewrite the browser and change everything? Is the Mozilla Corporation trying to force the community to use a new language?
+
+No. This is a research project. The point is to explore ideas. There is no plan to incorporate any Rust-based technology into Firefox.
+
+# Why GitHub rather than the normal Mozilla setup (Mercurial / Bugzilla / Tinderbox)?
+
+* This is a fresh codebase and has no existing ties to Mozilla infrastructure; there is no particular advantage to (re)using any of the above infrastructure, it would all have to be upgraded and adapted to our needs.
+* Git has been progressing rapidly in the years since Mozilla picked Mercurial for its main development needs, and appears to be both more widely known and more accessible at this point.
+* This reduces the administrative requirements for contributing to merely establishing a paper trail via a contributor agreement. There is no need for vouching, granting commit access to Mozilla facilities, or setting up Mozilla user accounts.
+
+# Why a BSD-style license rather than MPL or tri-license?
+
+* Partly due to preference of the original developer (Graydon).
+* Partly due to the fact that languages tend to have a wider audience and more diverse set of possible embeddings and end-uses than focused, coherent products such as web browsers. We'd like to appeal to as many of those potential contributors as possible.
--- /dev/null
+% Usage FAQ
+
+# How do I get my program to display the output of `log` statements?
+
+**Short answer** set the RUST_LOG environment variable to the name of your source file, sans extension.
+
+```sh
+rustc hello.rs
+export RUST_LOG=hello
+./hello
+```
+
+**Long answer** RUST_LOG takes a 'logging spec' that consists of a comma-separated list of paths, where a path consists of the crate name and sequence of module names, each separated by double-colons. For standalone .rs files the crate is implicitly named after the source file, so in the above example we were setting RUST_LOG to the name of the hello crate. Multiple paths can be combined to control the exact logging you want to see. For example, when debugging linking in the compiler you might set `RUST_LOG=rustc::metadata::creader,rustc::util::filesearch,rustc::back::rpath`
+
+If you aren't sure which paths you need, try setting RUST_LOG to `::help` and running your program. This will print a list of paths available for logging. For a full description see [the language reference][1].
+
+[1]:http://doc.rust-lang.org/doc/master/rust.html#logging-system
+
+# How do I get my program to display the output of `debug!` statements?
+
+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`?
+
+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.
--- /dev/null
+<style>
+ /* Display the full TOC */
+ #TOC ul ul {
+ display: block;
+ padding-left: 2em;
+ }
+ #influences blockquote p:last-child {
+ color: #999;
+ }
+</style>
--- /dev/null
+% Rust documentation
+
+# Reference docs
+
+**Current (0.9)**
+
+* [Tutorial](http://doc.rust-lang.org/doc/0.9/tutorial.html)
+* Guides
+ * [borrowed pointers](http://doc.rust-lang.org/doc/0.9/guide-borrowed-ptr.html)
+ * [conditions](http://doc.rust-lang.org/doc/0.9/guide-conditions.html)
+ * [containers & iterators](http://doc.rust-lang.org/doc/0.9/guide-container.html)
+ * [ffi](http://doc.rust-lang.org/doc/0.9/guide-ffi.html)
+ * [macros](http://doc.rust-lang.org/doc/0.9/guide-macros.html)
+ * [rustpkg](http://doc.rust-lang.org/doc/0.9/guide-rustpkg.html)
+ * [tasks](http://doc.rust-lang.org/doc/0.9/guide-tasks.html)
+ * [testing](http://doc.rust-lang.org/doc/0.9/guide-testing.html)
+* [Manual](http://doc.rust-lang.org/doc/0.9/rust.html) ([PDF](http://doc.rust-lang.org/doc/0.9/rust.pdf))
+* [Standard library](http://doc.rust-lang.org/doc/0.9/std/index.html)
+* [Extra library](http://doc.rust-lang.org/doc/0.9/extra/index.html)
+* [Package manager](http://doc.rust-lang.org/doc/0.9/rustpkg.html)
+
+**In-development (git master)**
+
+* [Tutorial](http://doc.rust-lang.org/doc/master/tutorial.html) ([PDF](http://doc.rust-lang.org/doc/master/tutorial.pdf))
+* Guides
+ * [borrowed pointers](http://doc.rust-lang.org/doc/master/guide-borrowed-ptr.html)
+ * [conditions](http://doc.rust-lang.org/doc/master/guide-conditions.html)
+ * [containers & iterators](http://doc.rust-lang.org/doc/master/guide-container.html)
+ * [ffi](http://doc.rust-lang.org/doc/master/guide-ffi.html)
+ * [macros](http://doc.rust-lang.org/doc/master/guide-macros.html)
+ * [rustpkg](http://doc.rust-lang.org/doc/master/guide-rustpkg.html)
+ * [tasks](http://doc.rust-lang.org/doc/master/guide-tasks.html)
+ * [testing](http://doc.rust-lang.org/doc/master/guide-testing.html)
+* [Manual](http://doc.rust-lang.org/doc/master/rust.html) ([PDF](http://doc.rust-lang.org/doc/master/rust.pdf))
+* [Standard library](http://doc.rust-lang.org/doc/master/std/index.html)
+* [Extra library](http://doc.rust-lang.org/doc/master/extra/index.html)
+* [libgreen](http://static.rust-lang.org/doc/master/green/index.html)
+* [libnative](http://static.rust-lang.org/doc/master/native/index.html)
+* [Package manager](http://doc.rust-lang.org/doc/master/rustpkg.html)
+
+# FAQs
+
+* [Language FAQ][lang-faq]
+* [Project FAQ][project-faq]
+* [Usage FAQ][usage-faq]
+* [Code cheatsheet][cheatsheet] - "How do I do X?"
+* [HOWTO submit a bug report][bugreport]
+
+[lang-faq]: complement-lang-faq.html
+[project-faq]: complement-project-faq.html
+[usage-faq]: complement-usage-faq.html
+[cheatsheet]: complement-cheatsheet.html
+[bugreport]: complement-bugreport.html
+
+# Community
+
+
+ > **Note** that to guard against botnet attacks we occasionally turn on moderation, disallowing
+ > unregistered users from joining or talking. You may need to [register](https://wiki.mozilla.org/IRC#Register_your_nickname) your nickname. Sorry for the inconvenience.*
+
+* IRC
+ * [#rust on irc.mozilla.org][pound-rust] - Main Rust channel - general discussion
+ * [#rust-internals on irc.mozilla.org][pound-rust-internals] - Rust compiler and library development
+ * [#rust-gamedev on irc.mozilla.org][pound-rust-gamedev] - game development in Rust
+ * [#rust-osdev on irc.mozill.org][pound-rust-osdev] - OS development in Rust
+ * [#rust on irc.ozinger.org][pound-rust-korea] - Korean Rust community
+
+* Mailing list [rust-dev]
+* Reddit's [r/rust]
+* User groups
+ * [Rust Bay Area][rust-bay-area]
+ * [Rust Korea][rust-korea]
+ * [Rust Skåne][rust-skane]
+ * [Rust 中文圈][rust-zh] (on Google+)
+
+[pound-rust]: http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust
+[pound-rust-internals]: http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-internals
+[pound-rust-gamedev]: http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-gamedev
+[pound-rust-osdev]: http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-osdev
+[pound-rust-korea]: http://chat.mibbit.com/?server=irc.ozinger.org&channel=%23rust
+[rust-dev]: https://mail.mozilla.org/listinfo/rust-dev
+[r/rust]: http://reddit.com/r/rust
+[rust-bay-area]: http://www.meetup.com/Rust-Bay-Area/
+[rust-korea]: http://rust-kr.org/
+[rust-skane]: http://www.meetup.com/rust-skane/
+[rust-zh]: https://plus.google.com/communities/100629002107624231185/
+
+# Specialized documentation
+
+[Releases][release-notes] - Links to current and old releases and documentation
+[Detailed release notes][detailed-release-notes] - Further explanation of language changes
+[Rust for C++ programmers][rust-for-c] - A cheat sheet
+[Rusticon][rust-icon] - A glossary of terms commonly used in Rust and Rust tools.
+[Unit testing][unit-testing] - Writing tests and running them with the built-in test driver
+[Using rustpkg][rustpkg] - Managing packages
+[Using rustdoc][rustdoc] - How to extract Markdown and HTML documentation from code
+[Package documentation](http://docs.octayn.net/) - Documentation for rust packages
+[Continuous integration][ci] - Test your GitHub-hosted packages with Travis CI
+[Reading and writing files][doc-rw]
+[Attributes][doc-attributes] - The role of metadata in Rust code, with descriptions of many applications
+[Packages, editors, and other tools][tools]
+[Packaging Terminology][doc-terminology]
+[Crate Hashes][crate-hashes] - How Rust generates crate filenames, versions symbols, and why
+[Computer Graphics and Game Development][game-dev] - Libraries and example projects
+[Présentation du langage Rust](http://lea-linux.org/documentations/Rust) - Detailed documentation in French, with examples
+[Building for Android][building-android]
+[Building for iOS][building-ios]
+
+[release-notes]: https://github.com/mozilla/rust/wiki/Doc-releases
+[detailed-release-notes]: https://github.com/mozilla/rust/wiki/Doc-detailed-release-notes
+[rust-for-c]: https://github.com/mozilla/rust/wiki/Rust-for-CXX-programmers
+[rust-icon]: https://github.com/mozilla/rust/wiki/The-Rusticon
+[unit-testing]: https://github.com/mozilla/rust/wiki/Doc-unit-testing
+[rustpkg]: https://github.com/mozilla/rust/wiki/Rustpkg
+[rustdoc]: https://github.com/mozilla/rust/wiki/Doc-using-rustdoc
+[ci]: https://github.com/mozilla/rust/wiki/Doc-continuous-integration
+[doc-rw]: https://github.com/mozilla/rust/wiki/Doc-reading-and-writing-files
+[doc-attributes]: https://github.com/mozilla/rust/wiki/Doc-attributes
+[tools]: https://github.com/mozilla/rust/wiki/Doc-packages%2C-editors%2C-and-other-tools
+[doc-terminology]: https://github.com/mozilla/rust/wiki/Doc-packaging-terminology
+[crate-hashes]: https://github.com/mozilla/rust/wiki/Doc-crate-hashes
+[game-dev]: https://github.com/mozilla/rust/wiki/Computer-Graphics-and-Game-Development
+[building-android]: https://github.com/mozilla/rust/wiki/Doc-building-for-android
+[building-ios]: https://github.com/mozilla/rust/wiki/Doc-building-for-ios
+
+Some Rust classics:
+
+* [Pointers in Rust: A Guide](http://words.steveklabnik.com/pointers-in-rust-a-guide)
+* [A taste of Rust](https://lwn.net/Articles/547145/)
+* [An overview of memory management in Rust](http://pcwalton.github.com/blog/2013/03/18/an-overview-of-memory-management-in-rust/)
+* [Which pointer should I use?](http://pcwalton.github.com/blog/2013/03/09/which-pointer-should-i-use/)
+* [Lifetimes explained](http://maikklein.github.io/2013/08/27/lifetimes-explained/)
+* [Little things that matter in language design](http://lwn.net/Articles/553131/)
+* [Operator overloading in Rust](http://maniagnosis.crsr.net/2013/04/operator-overloading-in-rust.html)
+* [Embedding Rust in Ruby](http://brson.github.com/2013/03/10/embedding-rust-in-ruby/)
+* [A first parallel program in Rust](http://blog.leahhanson.us/a-first-parallel-program-in-rust.html)
+* [FizzBuzz revisited](http://composition.al/blog/2013/03/02/fizzbuzz-revisited/)
+* [Ownership types in Rust, and whether they're worth it](http://tim.dreamwidth.org/1784423.html)
+* [Reasoning about the heap in Rust](http://johnbender.us/2013/04/30/reasoning-about-the-heap-in-rust)
+* [The Option Type](http://nickdesaulniers.github.io/blog/2013/05/07/rust-pattern-matching-and-the-option-type/)
+* [How I got started hacking rustc](http://cmr.github.io/blog/2013/06/23/how-i-got-started-with-rust/)
+* [Abstraction penalties, stack allocation, and ownership types](http://robert.ocallahan.org/2007/10/abstraction-penalties-stack-allocation_23.html)
+* [Présentation de Rust 0.8](http://linuxfr.org/news/presentation-de-rust-0-8) - A very detailed article about Rust 0.8, in French!
+
+# Presentations
+
+* [John Clements, 10-minute talk (video)](http://www.youtube.com/watch?v=_KgXy7jnwhY) at SoCal PLS on Rust, Macros, and Hygiene. December 2013.
+* [Felix's Codemesh 2013 slides](http://pnkfelix.github.io/present-rust-codemesh2013/fklock-rust-codemesh2013.pdf)
+* Geoffroy Couprie's [Scala.IO 2013 slides](http://dev.unhandledexpression.com/slides/rust-scalaio/)
+* Steve's presentation at RuPy 2013 "Nobody Knows Rust." [slides](http://steveklabnik.github.io/nobody_knows_rust/#/), video to come soon
+* [Tim's presentation at OS Bridge 2013](http://opensourcebridge.org/sessions/970) - And [slides](http://opensourcebridge.org/wiki/2013/Rust%3A_A_Friendly_Introduction)
+* [Niko's presentation at Northeastern](http://smallcultfollowing.com/babysteps/blog/2013/07/18/rust-presentation-at-northeastern/) - Slides only
+* [An I/O system for Rust](https://air.mozilla.org/intern-presentations-reed/) - Eric Reed's intern presentation on I/O
+* [Types of Types](https://air.mozilla.org/ben-blum-from-the-research-team-presents-types-of-types-in-rust/) - Ben Blum's intern presentation on 'kinds'
+* [Default methods in Rust](https://air.mozilla.org/intern-presentation-sullivan/) - Michael Sullivan's intern presentation on default methods
+* [A work stealing runtime for Rust](https://air.mozilla.org/2013-intern-todd/) - Aaron Todd's intern presentation on the Rust scheduler
+* [Dave Herman's StrangeLoop 2012 talk](http://www.infoq.com/presentations/Rust)
+++ /dev/null
-<style>
- /* Display the full TOC */
- #TOC ul ul {
- display: block;
- padding-left: 2em;
- }
- #influences blockquote p:last-child {
- color: #999;
- }
-</style>
\ No newline at end of file
list-style-type: none;
padding-left: 0px;
}
+
/* Only display one level of hierarchy in the TOC */
#TOC ul ul {
display: none;
border-top: 1px solid #eeeeee;
}
+table {
+ border-collapse: collapse;
+ border-spacing: 0;
+}
+
+table tr.odd {
+ background: #eee;
+}
+
+table td,
+table th {
+ border: 1px solid #ddd;
+ padding: 5px;
+}
+
@media print {
* {
text-shadow: none !important;
* [Documenting Rust code][rustdoc]
* [Testing Rust code][testing]
-There is further documentation on the [wiki], however those tend to be even
-more out of date than this document.
+There is further documentation on the [Main Page](index.html).
[borrow]: guide-borrowed-ptr.html
[tasks]: guide-tasks.html
[testing]: guide-testing.html
[rustdoc]: rustdoc.html
-[wiki]: https://github.com/mozilla/rust/wiki/Docs
[wiki-packages]: https://github.com/mozilla/rust/wiki/Doc-packages,-editors,-and-other-tools
DOCS :=
CDOCS :=
DOCS_L10N :=
+HTML_DEPS :=
BASE_DOC_OPTS := --from=markdown --standalone --toc --number-sections
-
HTML_OPTS = $(BASE_DOC_OPTS) --to=html5 --section-divs --css=rust.css \
--include-before-body=doc/version_info.html \
--include-in-header=doc/favicon.inc
-
TEX_OPTS = $(BASE_DOC_OPTS) --to=latex
EPUB_OPTS = $(BASE_DOC_OPTS) --to=epub
# Docs, from pandoc, rustdoc (which runs pandoc), and node
######################################################################
+HTML_DEPS += doc/rust.css
doc/rust.css: rust.css
@$(call E, cp: $@)
$(Q)cp -a $< $@ 2> /dev/null
-doc/manual.inc: manual.inc
+doc/full-toc.inc: full-toc.inc
@$(call E, cp: $@)
$(Q)cp -a $< $@ 2> /dev/null
+HTML_DEPS += doc/favicon.inc
doc/favicon.inc: favicon.inc
@$(call E, cp: $@)
$(Q)cp -a $< $@ 2> /dev/null
ifneq ($(NO_DOCS),1)
DOCS += doc/rust.html
-doc/rust.html: rust.md doc/version_info.html doc/rust.css doc/manual.inc \
- doc/favicon.inc
+doc/rust.html: rust.md doc/version_info.html doc/full-toc.inc $(HTML_DEPS)
@$(call E, pandoc: $@)
$(Q)$(CFG_NODE) $(S)doc/prep.js --highlight $< | \
- $(CFG_PANDOC) $(HTML_OPTS) --include-in-header=doc/manual.inc --output=$@
+ $(CFG_PANDOC) $(HTML_OPTS) --include-in-header=doc/full-toc.inc --output=$@
DOCS += doc/rust.tex
doc/rust.tex: rust.md doc/version.md
$(CFG_PANDOC) $(EPUB_OPTS) --output=$@
DOCS += doc/rustpkg.html
-doc/rustpkg.html: rustpkg.md doc/version_info.html doc/rust.css \
- doc/favicon.inc
+doc/rustpkg.html: rustpkg.md doc/version_info.html $(HTML_DEPS)
@$(call E, pandoc: $@)
$(Q)$(CFG_NODE) $(S)doc/prep.js --highlight $< | \
$(CFG_PANDOC) $(HTML_OPTS) --output=$@
DOCS += doc/rustdoc.html
-doc/rustdoc.html: rustdoc.md doc/version_info.html doc/rust.css \
- doc/favicon.inc
+doc/rustdoc.html: rustdoc.md doc/version_info.html $(HTML_DEPS)
@$(call E, pandoc: $@)
$(Q)$(CFG_NODE) $(S)doc/prep.js --highlight $< | \
$(CFG_PANDOC) $(HTML_OPTS) --output=$@
DOCS += doc/tutorial.html
-doc/tutorial.html: tutorial.md doc/version_info.html doc/rust.css \
- doc/favicon.inc
+doc/tutorial.html: tutorial.md doc/version_info.html $(HTML_DEPS)
@$(call E, pandoc: $@)
$(Q)$(CFG_NODE) $(S)doc/prep.js --highlight $< | \
$(CFG_PANDOC) $(HTML_OPTS) --output=$@
--include-before-body=doc/version_info.html \
--output=$@
+# Complementary documentation
+#
+DOCS += doc/index.html
+doc/index.html: index.md $(HTML_DEPS)
+ @$(call E, pandoc: $@)
+ $(Q)$(CFG_NODE) $(S)doc/prep.js --highlight $< | \
+ $(CFG_PANDOC) $(HTML_OPTS) --output=$@
+
+DOCS += doc/complement-lang-faq.html
+doc/complement-lang-faq.html: $(S)doc/complement-lang-faq.md doc/full-toc.inc $(HTML_DEPS)
+ @$(call E, pandoc: $@)
+ $(Q)$(CFG_NODE) $(S)doc/prep.js --highlight $< | \
+ $(CFG_PANDOC) $(HTML_OPTS) --include-in-header=doc/full-toc.inc --output=$@
+
+DOCS += doc/complement-project-faq.html
+doc/complement-project-faq.html: $(S)doc/complement-project-faq.md $(HTML_DEPS)
+ @$(call E, pandoc: $@)
+ $(Q)$(CFG_NODE) $(S)doc/prep.js --highlight $< | \
+ $(CFG_PANDOC) $(HTML_OPTS) --output=$@
+
+DOCS += doc/complement-usage-faq.html
+doc/complement-usage-faq.html: $(S)doc/complement-usage-faq.md $(HTML_DEPS)
+ @$(call E, pandoc: $@)
+ $(Q)$(CFG_NODE) $(S)doc/prep.js --highlight $< | \
+ $(CFG_PANDOC) $(HTML_OPTS) --output=$@
+
+DOCS += doc/complement-cheatsheet.html
+doc/complement-cheatsheet.html: $(S)doc/complement-cheatsheet.md doc/full-toc.inc $(HTML_DEPS)
+ @$(call E, pandoc: $@)
+ $(Q)$(CFG_NODE) $(S)doc/prep.js --highlight $< | \
+ $(CFG_PANDOC) $(HTML_OPTS) --include-in-header=doc/full-toc.inc --output=$@
+
+DOCS += doc/complement-bugreport.html
+doc/complement-bugreport.html: $(S)doc/complement-bugreport.md $(HTML_DEPS)
+ @$(call E, pandoc: $@)
+ $(Q)$(CFG_NODE) $(S)doc/prep.js --highlight $< | \
+ $(CFG_PANDOC) $(HTML_OPTS) --output=$@
+
# Guides
DOCS += doc/guide-macros.html
projects / rust.git / commitdiff