---

yaml
---
r: 145264
b: refs/heads/try2
c: 068e042
h: refs/heads/master
v: v3

Author: bors

[refs]

@@ -5,7 +5,7 @@ refs/heads/snap-stage3: 78a7676898d9f80ab540c6df5d4c9ce35bb50463
 refs/heads/try: 519addf6277dbafccbb4159db4b710c37eaa2ec5
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b
-refs/heads/try2: 3bd0eb9f637794cefbdb700d4fbe125369de53dd
+refs/heads/try2: 068e04231ded7fccca349babb1ba58ab3d796f40
 refs/heads/dist-snap: ba4081a5a8573875fed17545846f6f6902c8ba8d
 refs/tags/release-0.2: c870d2dffb391e14efb05aa27898f1f6333a9596
 refs/tags/release-0.3: b5f0d0f648d9a6153664837026ba1be43d3e2503

branches/try2/.gitattributes

@@ -1,13 +1,10 @@
 [attr]rust text eol=lf whitespace=tab-in-indent,trailing-space,tabwidth=4
 
-* text=auto
+* text eol=lf
 *.cpp rust
 *.h rust
 *.rs rust
 src/rt/msvc/* -whitespace
 src/rt/vg/* -whitespace
 src/rt/linenoise/* -whitespace
 src/rt/jemalloc/**/* -whitespace
-src/rt/jemalloc/include/jemalloc/jemalloc.h.in text eol=lf
-src/rt/jemalloc/include/jemalloc/jemalloc_defs.h.in text eol=lf
-src/rt/jemalloc/include/jemalloc/internal/jemalloc_internal.h.in text eol=lf

branches/try2/Makefile.in

@@ -442,6 +442,7 @@ CSREQ$(1)_T_$(2)_H_$(3) = \
 	$$(TSREQ$(1)_T_$(2)_H_$(3)) \
 	$$(HBIN$(1)_H_$(3))/rustpkg$$(X_$(3)) \
 	$$(HBIN$(1)_H_$(3))/rustdoc$$(X_$(3)) \
+	$$(HBIN$(1)_H_$(3))/rustdoc_ng$$(X_$(3)) \
 	$$(HBIN$(1)_H_$(3))/rusti$$(X_$(3)) \
 	$$(HBIN$(1)_H_$(3))/rust$$(X_$(3)) \
 	$$(HLIB$(1)_H_$(3))/$(CFG_LIBRUSTPKG_$(3)) \

branches/try2/doc/rust.md

@@ -248,7 +248,7 @@ string_body : non_double_quote
             | '\x5c' [ '\x22' | common_escape ] ;
 
 common_escape : '\x5c'
-              | 'n' | 'r' | 't'
+              | 'n' | 'r' | 't' | '0'
               | 'x' hex_digit 2
               | 'u' hex_digit 4
               | 'U' hex_digit 8 ;
@@ -962,24 +962,76 @@ parameters to allow methods with that trait to be called on values
 of that type.
 
 
-#### Unsafe functions
-
-Unsafe functions are those containing unsafe operations that are not contained in an [`unsafe` block](#unsafe-blocks).
-Such a function must be prefixed with the keyword `unsafe`.
+#### Unsafety
 
 Unsafe operations are those that potentially violate the memory-safety guarantees of Rust's static semantics.
-Specifically, the following operations are considered unsafe:
+
+The following language level features cannot be used in the safe subset of Rust:
 
   - Dereferencing a [raw pointer](#pointer-types).
-  - Casting a [raw pointer](#pointer-types) to a safe pointer type.
-  - Calling an unsafe function.
+  - Calling an unsafe function (including an intrinsic or foreign function).
 
-##### Unsafe blocks
+##### Unsafe functions
 
-A block of code can also be prefixed with the `unsafe` keyword, to permit a sequence of unsafe operations in an otherwise-safe function.
-This facility exists because the static semantics of Rust are a necessary approximation of the dynamic semantics.
-When a programmer has sufficient conviction that a sequence of unsafe operations is actually safe, they can encapsulate that sequence (taken as a whole) within an `unsafe` block. The compiler will consider uses of such code "safe", to the surrounding context.
+Unsafe functions are functions that are not safe in all contexts and/or for all possible inputs.
+Such a function must be prefixed with the keyword `unsafe`.
+
+##### Unsafe blocks
 
+A block of code can also be prefixed with the `unsafe` keyword, to permit calling `unsafe` functions
+or dereferencing raw pointers within a safe function.
+
+When a programmer has sufficient conviction that a sequence of potentially unsafe operations is
+actually safe, they can encapsulate that sequence (taken as a whole) within an `unsafe` block. The
+compiler will consider uses of such code safe, in the surrounding context.
+
+Unsafe blocks are used to wrap foreign libraries, make direct use of hardware or implement features
+not directly present in the language. For example, Rust provides the language features necessary to
+implement memory-safe concurrency in the language but the implementation of tasks and message
+passing is in the standard library.
+
+Rust's type system is a conservative approximation of the dynamic safety requirements, so in some
+cases there is a performance cost to using safe code.  For example, a doubly-linked list is not a
+tree structure and can only be represented with managed or reference-counted pointers in safe code.
+By using `unsafe` blocks to represent the reverse links as raw pointers, it can be implemented with
+only owned pointers.
+
+##### Behavior considered unsafe
+
+This is a list of behavior which is forbidden in all Rust code. Type checking provides the guarantee
+that these issues are never caused by safe code. An `unsafe` block or function is responsible for
+never invoking this behaviour or exposing an API making it possible for it to occur in safe code.
+
+* Data races
+* Dereferencing a null/dangling raw pointer
+* Mutating an immutable value/reference, if it is not marked as non-`Freeze`
+* Reads of [undef](http://llvm.org/docs/LangRef.html#undefined-values) (uninitialized) memory
+* Breaking the [pointer aliasing rules](http://llvm.org/docs/LangRef.html#pointer-aliasing-rules)
+  with raw pointers (a subset of the rules used by C)
+* Invoking undefined behavior via compiler intrinsics:
+    * Indexing outside of the bounds of an object with `std::ptr::offset` (`offset` intrinsic), with
+      the exception of one byte past the end which is permitted.
+    * Using `std::ptr::copy_nonoverlapping_memory` (`memcpy32`/`memcpy64` instrinsics) on
+      overlapping buffers
+* Invalid values in primitive types, even in private fields/locals:
+    * Dangling/null pointers in non-raw pointers, or slices
+    * A value other than `false` (0) or `true` (1) in a `bool`
+    * A discriminant in an `enum` not included in the type definition
+    * A value in a `char` which is a surrogate or above `char::MAX`
+    * non-UTF-8 byte sequences in a `str`
+
+##### Behaviour not considered unsafe
+
+This is a list of behaviour not considered *unsafe* in Rust terms, but that may be undesired.
+
+* Deadlocks
+* Reading data from private fields (`std::repr`, `format!("{:?}", x)`)
+* Leaks due to reference count cycles, even in the global heap
+* Exiting without calling destructors
+* Sending signals
+* Accessing/modifying the file system
+* Unsigned integer overflow (well-defined as wrapping)
+* Signed integer overflow (well-defined as two's complement representation wrapping)
 
 #### Diverging functions
 

branches/try2/doc/tutorial-ffi.md

@@ -321,7 +321,7 @@ impl<T: Send> Unique<T> {
 
 #[unsafe_destructor]
 impl<T: Send> Drop for Unique<T> {
-    fn drop(&self) {
+    fn drop(&mut self) {
         #[fixed_stack_segment];
         #[inline(never)];
         

branches/try2/doc/tutorial-rustpkg.md

@@ -0,0 +1,223 @@
+% Rust Packaging Tutorial
+
+# Introduction
+
+Sharing is caring. Rust comes with a tool, `rustpkg`, which allows you to
+package up your Rust code and share it with other people. This tutorial will
+get you started on all of the concepts and commands you need to give the gift
+of Rust code to someone else.
+
+## Installing External Packages
+
+First, let's try to use an external package somehow. I've made a sample package
+called `hello` to demonstrate how to do so.  Here's how `hello` is used:
+
+~~~~
+extern mod hello;
+
+fn main() {
+    hello::world();
+}
+~~~~
+
+Easy! But if you try to compile this, you'll get an error:
+
+~~~~ {.notrust}
+$ rustc main.rs 
+main.rs:1:0: 1:17 error: can't find crate for `hello`
+main.rs:1 extern mod hello;
+          ^~~~~~~~~~~~~~~~~
+
+~~~~
+
+This makes sense, as we haven't gotten it from anywhere yet!  Luckily for us,
+`rustpkg` has an easy way to fetch others' code: the `install` command. It's
+used like this:
+
+~~~ {.notrust}
+$ rustpkg install pkg_id
+~~~
+
+This will install a package named 'pkg_id' into your current Rust environment.
+I called it 'pkg_id' in this example because `rustpkg` calls this a 'package
+identifier.' When using it with an external package like this, it's often a
+URI fragment.  You see, Rust has no central authority for packages. You can
+build your own `hello` library if you want, and that's fine. We'd both host
+them in different places and different projects would rely on whichever version
+they preferred.
+
+To install the `hello` library, simply run this in your terminal:
+
+~~~ {.notrust}
+$ rustpkg install github.com/steveklabnik/hello
+~~~
+
+You should see a message that looks like this:
+
+~~~ {.notrust}
+note: Installed package github.com/steveklabnik/hello-0.1 to /some/path/.rust
+~~~
+
+Now, compiling our example should work:
+
+~~~ {.notrust}
+$ rustc main.rs
+$ ./main 
+Hello, world.
+~~~
+
+Simple! That's all it takes.
+
+## Workspaces
+
+Before we can talk about how to make packages of your own, you have to
+understand the big concept with `rustpkg`: workspaces. A 'workspace' is simply
+a directory that has certain sub-directories that `rustpkg` expects. Different
+Rust projects will go into different workspaces.
+
+A workspace consists of any directory that has the following
+directories:
+
+* `src`: The directory where all the source code goes.
+* `build`: This directory contains all of the build output.
+* `lib`: The directory where any libraries distributed with the package go.
+* `bin`: This directory holds any binaries distributed with the package.
+
+There are also default file names you'll want to follow as well:
+
+* `main.rs`: A file that's going to become an executable.
+* `lib.rs`: A file that's going to become a library.
+
+## Building your own Package
+
+Now that you've got workspaces down, let's build your own copy of `hello`. Go
+to wherever you keep your personal projects, and let's make all of the
+directories we'll need. I'll refer to this personal project directory as
+`~/src` for the rest of this tutorial.
+
+### Creating our workspace
+
+~~~ {.notrust}
+$ cd ~/src
+$ mkdir -p hello/src/hello
+$ cd hello
+~~~
+
+Easy enough! Let's do one or two more things that are nice to do:
+
+~~~ {.notrust}
+$ git init .
+$ cat > README.md
+# hello
+
+A simple package for Rust.
+
+## Installation
+
+```
+$ rustpkg install github.com/YOUR_USERNAME/hello
+```
+^D
+$ cat > .gitignore
+.rust
+build
+^D
+$ git commit -am "Initial commit."
+~~~
+
+If you're not familliar with the `cat >` idiom, it will make files with the
+text you type inside. Control-D (`^D`) ends the text for the file.
+
+Anyway, we've got a README and a `.gitignore`. Let's talk about that
+`.gitignore` for a minute: we are ignoring two directories, `build` and
+`.rust`. `build`, as we discussed earlier, is for build artifacts, and we don't
+want to check those into a repository. `.rust` is a directory that `rustpkg`
+uses to keep track of its own settings, as well as the source code of any other
+external packages that this workspace uses. This is where that `rustpkg
+install` puts all of its files. Those are also not to go into our repository,
+so we ignore it all as well.
+
+Next, let's add a source file:
+
+~~~
+#[desc = "A hello world Rust package."];
+#[license = "MIT"];
+
+pub fn world() {
+    println("Hello, world.");
+}
+~~~
+
+Put this into `src/hello/lib.rs`. Let's talk about each of these attributes:
+
+### Crate attributes for packages
+
+`license` is equally simple: the license we want this code to have. I chose MIT
+here, but you should pick whatever license makes the most sense for you.
+
+`desc` is a description of the package and what it does. This should just be a
+sentence or two.
+
+### Building your package
+
+Building your package is simple:
+
+~~~ {.notrust}
+$ rustpkg build hello
+~~~
+
+This will compile `src/hello/lib.rs` into a library. After this process
+completes, you'll want to check out `build`:
+
+~~~ {.notrust}
+$ ls build/x86_64-unknown-linux-gnu/hello/
+libhello-ed8619dad9ce7d58-0.1.0.so
+~~~
+
+This directory naming structure is called a 'build triple,' and is because I'm
+on 64 bit Linux. Yours may differ based on platform.
+
+You'll also notice that `src/hello/lib.rs` turned into
+`libhello-ed8619dad9ce7d58-0.1.0.so`. This is a simple combination of the
+library name, a hash of its content, and the version.
+
+Now that your library builds, you'll want to commit:
+
+~~~ {.notrust}
+$ git add src
+$ git commit -m "Adding source code."
+~~~
+
+If you're using GitHub, after creating the project, do this:
+
+~~~ {.notrust}
+$ git remote add origin [email protected]:YOUR_USERNAME/hello.git
+$ git push origin -u master
+~~~
+
+Now you can install and use it! Go anywhere else in your filesystem:
+
+~~~ {.notrust}
+$ cd ~/src/foo
+$ rustpkg install github/YOUR_USERNAME/hello
+WARNING: The Rust package manager is experimental and may be unstable
+note: Installed package github.com/YOUR_USERNAME/hello-0.1 to /home/yourusername/src/hello/.rust
+~~~
+
+That's it!
+
+## More resources
+
+There's a lot more going on with `rustpkg`, this is just to get you started.
+Check out [the rustpkg manual](rustpkg.html) for the full details on how to
+customize `rustpkg`.
+
+A tag was created on GitHub specifically for `rustpkg`-related issues. You can
+[see all the Issues for rustpkg
+here](https://github.com/mozilla/rust/issues?direction=desc&labels=A-pkg&sort=created&state=open),
+with bugs as well as new feature plans. `rustpkg` is still under development,
+and so may be a bit flaky at the moment.
+
+You may also want to check out [this blog
+post](http://tim.dreamwidth.org/1820526.html), which contains some of the early
+design decisions and justifications.

branches/try2/doc/tutorial-tasks.md

@@ -47,16 +47,14 @@ concurrency at this writing:
 
 * [`std::task`] - All code relating to tasks and task scheduling,
 * [`std::comm`] - The message passing interface,
-* [`std::pipes`] - The underlying messaging infrastructure,
-* [`extra::comm`] - Additional messaging types based on `std::pipes`,
+* [`extra::comm`] - Additional messaging types based on `std::comm`,
 * [`extra::sync`] - More exotic synchronization tools, including locks,
 * [`extra::arc`] - The Arc (atomically reference counted) type,
   for safely sharing immutable data,
 * [`extra::future`] - A type representing values that may be computed concurrently and retrieved at a later time.
 
 [`std::task`]: std/task.html
 [`std::comm`]: std/comm.html
-[`std::pipes`]: std/pipes.html
 [`extra::comm`]: extra/comm.html
 [`extra::sync`]: extra/sync.html
 [`extra::arc`]: extra/arc.html
@@ -125,7 +123,7 @@ receiving messages. Pipes are low-level communication building-blocks and so
 come in a variety of forms, each one appropriate for a different use case. In
 what follows, we cover the most commonly used varieties.
 
-The simplest way to create a pipe is to use the `pipes::stream`
+The simplest way to create a pipe is to use the `comm::stream`
 function to create a `(Port, Chan)` pair. In Rust parlance, a *channel*
 is a sending endpoint of a pipe, and a *port* is the receiving
 endpoint. Consider the following example of calculating two results