Bluish Coder: rust

Contributing to Servo

2015-03-24T16:00:00+13:00

Servo is a web browser engine written in the Rust programming language. It is being developed by Mozilla. Servo is open source and the project is developed on github.

I was looking for a small project to do some Rust programming and Servo being written in Rust seemed likely to have tasks that were small enough to do in my spare time yet be useful contributions to the project. This post outlines how I built Servo, found issues to work on, and got them merged.

Preparing Servo

The Servo README has details on the pre-requisites needed. Installing the pre-requisites and cloning the repository on Ubuntu was:

$ sudo apt-get install curl freeglut3-dev \
   libfreetype6-dev libgl1-mesa-dri libglib2.0-dev xorg-dev \
   msttcorefonts gperf g++ cmake python-virtualenv \
   libssl-dev libbz2-dev libosmesa6-dev 
...
$ git clone https://github.com/servo/servo

Building Rust

The Rust programming language has been fairly volatile in terms of language and library changes. Servo deals with this by requiring a specific git commit of the Rust compiler to build. The Servo source is periodically updated for new Rust versions. The commit id for Rust that is required to build is stored in the rust-snapshot-hash file in the Servo repository.

If the Rust compiler isn't installed already there are two options for building Servo. The first is to build the required version of Rust yourself, as outlined below. The second is to let the Servo build system, mach, download a binary snapshot and use that. If you wish to do the latter, and it may make things easier when starting out, skip this step to build Rust.

$ cat servo/rust-snapshot-hash
d3c49d2140fc65e8bb7d7cf25bfe74dda6ce5ecf/rustc-1.0.0-dev
$ git clone https://github.com/rust-lang/rust
$ cd rust
$ git checkout -b servo d3c49d2140fc65e8bb7d7cf25bfe74dda6ce5ecf
$ ./configure --prefix=/home/myuser/rust
$ make
$ make install

Note that I configure Rust to be installed in a directory off my home directory. I do this out of preference to enable managing different Rust versions. The build will take a long time and once built you need to add the prefix directories to the PATH:

$ export PATH=$PATH:/home/myuser/rust/bin
$ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/myuser/rust/lib

Building Servo

There is a configuration file used by the Servo build system to store information on what Rust compiler to use, whether to use a system wide Cargo (Rust package manager) install and various paths. This file, .servobuild, should exist in the root of the Servo source that was cloned. There is a sample file that can be used as a template. The values I used were:

[tools]
system-rust = true
system-cargo = false

[build]
android = false
debug-mozjs = false

If you want to use a downloaded binary snapshot of Rust to build Servo you should set the system-rust setting to false. With it set to true as above it will expect to find a Rust of the correct version in the path.

Servo uses the mach command line interface that is used to build Firefox. Once the .servobuild is created then Servo can be built with:

$ ./mach build

Servo can be run with:

$ ./mach run http://bluishcoder.co.nz

To run the test suite:

$ ./mach test

Finding something to work on

The github issue list has three useful labels for finding work. They are:

For my first task I searched for E-easy issues that were not currently assigned (using the C-assigned label). I commented in the issue asking if I could work on it and it was then assigned to me by a Servo maintainer.

Submitting the Fix

Fixing the issue involved:

Fork the Servo repository on github.
Clone my fork localling and make the changes required to the source in a branch I created for the issue I was working on.
Commit the changes locally and push them to my fork on github.
Raise a pull request for my branch.

Raising the pull request runs a couple of automated actions on the Servo repository. The first is an automated response thanking you for the changes followed by a link to the external critic review system.

Reviews

The Servo project uses the Critic review tool. This will contain data from your pull request and any reviews made by Servo reviewers.

To address reviews I made the required changes and committed them to my local branch as seperate commits using the fixup flag to git commit. This associates the new commit with the original commit that contained the change. It allows easier squashing later.

$ git commit --fixup=<commit id of original commit>

The changes are then pushed to the github fork and the previously made pull request is automatically updated. The Critic review tool also automatically picks up the change and will associate the fix with the relevant lines in the review.

With some back and forth the changes get approved and a request might be made to squash the commits. If fixup was used to record the review changes then they will be squashed into the correct commits when you rebase:

$ git fetch origin
$ git rebase --autosquash origin/master

Force pushing this to the fork will result in the pull request being updated. When the reviewer marks this as r+ the merge to master will start automatically, along with a build and test runs. If test failures happen these get added to the pull request and the review process starts again. If tests pass and it merges then it will be closed and the task is done.

A full overview of the process is available on the github wiki under Github and Critic PR handling 101.

Conclusion

The process overhead of committing to Servo is quite low. There are plenty of small tasks that don't require a deep knowledge of Rust. The first task I worked on was basically a search/replace. The second was more involved, implementing view-source protocol and text/plain handling. The latter allows the following to work in Servo:

$ ./mach run view-source:http://bluishcoder.co.nz
$ ./mach run http://cd.pn/plainttext.txt

The main issues I encountered working with Rust and Servo were:

Compiling Servo is quite slow. Even changing private functions in a module would result in other modules rebuilding. I assume this is due to cross module inlining.
I'd hoped to get away from intermittent test failures like there are in Gecko but there seems to be the occasional intermittent reftest failure.

The things I liked:

Very helpful Servo maintainers on IRC and in github/review comments.
Typechecking in Rust helped find errors early.
I found it easier comparing Servo code to HTML specifications and following them together than I do in Gecko.

I hope to contribute more as time permits.

Phantom Types in Rust

2013-08-15T18:00:00+12:00

Update 2013-08-16, I've updated the first example based on feedback from the hacker news, /r/rust, and /r/programming threads.

I attended an overview of how the Servo browser engine, written in the Rust programming language, implements the task of laying out of elements on a web page. Patrick Walton gave the talk and highlighted some of the implementation idioms in Servo. Phantom Types are used in a number of places so I thought I'd try some phantom type examples to help learn more about Rust and Servo.

DSL type checking

Rust supports generics. A phantom type is a type parameter that isn't used in the definition of the type. Imagine a datatype that is used to represent types in a simple DSL:

enum T  { TI(int), TS(~str) }

The type T has two constructors. A TI representing an integer and a TS representing a string. In Rust the ~ prefixing str means 'owned pointer to a string allocated on the heap'.

We have two functions that operate on this type. One to add two integers and the other to concatenate two strings:

fn plus (lhs: T, rhs: T) -> T
fn concat (lhs: T, rhs: T) -> T

Using these functions looks like:

let d1 = TI(1);
let d2 = TI(2);
let x = plus(d1, d2);
display(&x);

let d1 = TS(~"Hello, ");
let d2 = TS(~"World");
let y = concat (d1,d2);
display(&y);

Unforunately with the type definition of T it is possible to add an integer and a string:

let d1 = TI(1);
let d2 = TS(~"Hello, ");
let x = plus(d1, d2);
display(&x);

This won't be caught at compile time but, assuming the plus function aborts on incorrect types, will fail at runtime. A full example that demonstrates this available in test1.rs. Compiling with rustc test.rs and running the resulting test produces:

int: 3
str: Hello, World
task <unnamed> failed at 'error', test1.rs:12

We can detect this issue at compile time by using phantom types. This involves changing the T type to be:

enum T<A>  { TI(int), TS(~str) }

Notice that the type index A does not appear anywhere in the type definition on the right hand side. The definitions of plus and concat are changed to have a different type for the type index A:

fn plus (lhs: T<int>, rhs: T<int>) -> T<int>
fn concat (lhs: T<~str>, rhs: T<~str>) -> T<~str>

We also have to change the code that creates the TI and TS types. Code like the following will successfully typecheck:

let d1 = TI(1);
let d2 = TS(~"hello");
let x = plus(d1, d2);

This is because d1 and d2 get their types inferred as T<int> due to plus requiring two T<int> types. What's needed is to constrain the types of d1 and d2 to T<int> and T<~str> at the point of definition. This can be done with:

let d1: T<int> = TI(1);
let d2: T<~str> = TS(~"foo");
let x = plus(d1, d2);

Unfortunately this will still work:

let d1: T<int> = TI(1);
let d2: T<int> = TS(~"foo");
let x = plus(d1, d2);

A better approach is to not use the constructors for the T<A> enum and instead create our own:

fn make_int (i: int)  -> T<int>  { TI(i) }
fn make_str (s: ~str) -> T<~str> { TS(s) }

Using these to create our values will ensure that they have the type of the argument passed to the function. Passing the wrong type is now an error:

let d1 = make_int(1);
let d2 = make_str(~"foo");
let x = plus(d1, d2);

In real code it's best to ensure that the constructors for T<A> aren't public to ensure that callers from outside the module can't create them and subvert our attempts at better type checking.

This code also ensures that the result of a plus cannot be used in a concat and vice versa. The following code produces a compile error:

fn main() {
  let d1 = TI(1);
  let d2 = TI(2);
  let x = plus(d1, d2);
  display(&x);

  let d1 = TS(~"Hello, ");
  let d2 = TS(~"World");
  let y = concat (d1,d2);
  display(&y);

  // Compile error here
  let z = concat(x, y);
  display(&z);
}

The full example is in test2.rs and compiling it results in:

test2.rs:45:17: 45:18 error: mismatched types:
  expected `T<~str>` but found `T<int>` (expected ~str but found int)
test2.rs:45   let z = concat(x, y);
                         ^

Commenting out the offending code allows the program to compile and run without errors. There is no runtime overhead or additional code generated when using phantom types. The types are erased at compile time and the resulting program is as if they hadn't been used at all - except that you know the code won't have the runtime failure as it passed type checking.

Safer strings

Another use of phantom types is for providing a taint to string types so they can't be used in an unsafe manner. An example of this is generating HTML template pages as the response to an HTTP request. The page is generated by concatenating various strings together. A string that comes from user input must be properly escaped before it is allowed to be embedded in an HTML page.

In this example we have a type representing an HTML fragment used to compose an HTML page to be generated:

enum Fragment { Str(~str) }

It only has one constructor, Str, which holds the unique string containing the page data. A render_page function displays a complete page:

fn get_str(s: Fragment) -> ~str {
  match s {
    Str(s) => { s }
  }
}

fn render_page(s: Fragment) {
  println(get_str(s));
}

Functions exist to generate the head and body of the page with the latter including some form of data obtained elsewhere. Perhaps user input or the output of some other process:

fn get_head() -> Fragment {
  Str(~"<head></head>")
}  

fn get_body(s: Fragment) -> Fragment {
  Str("<body>" + get_str(s) + "</body>")
}

Data from untrusted sources needs to be 'blessed'. This should perform any escaping necessary to make the data safe to embed in the web page. The following is a main program that generates and displays the page:

fn main() {
  let user_input = get_user_input(~"<script>alert('oops')</script>");
  let page = generate_page(get_head(),
                           get_body(user_input));
  render_page(page);
}

This compiles and runs. The full example for trying it out is in test3.rs. The output is:

<html><head></head><body><script>alert('oops')</script></body></html>

Unfortunately we forgot to call bless and the user input was added unescaped. Ideally this should be a compile time error. If we add a phantom type to the Fragment class we can differentiate between safe and unsafe strings with no runtime overhead:

struct Safe;
struct Unsafe;

enum Fragment<T> { Str(~str) }

All the generation functions now require safe fragments:

fn generate_page(head: Fragment<Safe>, body: Fragment<Safe>) -> Fragment<Safe>
fn get_head() -> Fragment<Safe>
fn get_body(s: Fragment<Safe>) -> Fragment<Safe>
fn render_page(s: Fragment<Safe>)
fn bless(s: Fragment<Unsafe>) -> Fragment<Safe>

The exception is the function that obtains untrusted data. It returns an unsafe fragment:

fn get_user_input(s: ~str) -> Fragment<Unsafe>

Now the code that forgets to call bless (in test4.rs) results in a compile error:

test4.rs:41:36: 41:46 error: mismatched types: expected `Fragment<Safe>`
   but found `Fragment<Unsafe>` (expected struct Safe but found struct Unsafe)
test4.rs:41                            get_body(user_input));
                                            ^~~~~~~~~~

This approach can be used to help wherever untrusted data shouldn't be mixed with trusted data. Constructing SQL queries and generating URL's are other examples.

Servo

One of the uses of phantom types in Servo is in the Node type:

// A phantom type representing the script task's view of this node. Script is able to mutate
/// nodes but may not access layout data.
pub struct ScriptView;

/// A phantom type representing the layout task's view of the node. Layout is not allowed to mutate
/// nodes but may access layout data.
pub struct LayoutView;

/// An HTML node.
///
/// `View` describes extra data associated with this node that this task has access to. For
/// the script task, this is the unit type `()`. For the layout task, this is
/// `layout::aux::LayoutData`.
pub struct Node<View> {
  ...
}

A node has fields that should only be accessed or mutated on certain tasks. The script task can mutate nodes but cannot access data related to layout. The layout task is not allowed to mutate the node but can access the layout data. The prevents data races amongst the fields in the node.

The is implemented using phantom types. The node type is indexed over a View which can be ScriptView or LayoutView. There are methods implemented for Node<ScriptView> which makes them only accessible to the script task:

impl Node<ScriptView> {
  pub fn ....
}

An example of where the layout task gets the LayoutView version of a node is in handle_reflow. This takes a Reflow structure:

pub struct Reflow {
    /// The document node.
    document_root: AbstractNode<ScriptView>,
    /// The style changes that need to be done.
    damage: DocumentDamage,
    /// The goal of reflow: either to render to the screen or to flush layout info for script.
    goal: ReflowGoal,
    /// The URL of the page.
    url: Url,
    /// The channel through which messages can be sent back to the script task.
    script_chan: ScriptChan,
    /// The current window size.
    window_size: Size2D<uint>,
    /// The channel that we send a notification to.
    script_join_chan: Chan<()>,
}

Note the document_root is an AbstractNode<ScriptView>. Inside the handle_reflow function in the layout task it does:

/// The high-level routine that performs layout tasks.
fn handle_reflow(&mut self, data: &Reflow) {
    // FIXME: Isolate this transmutation into a "bridge" module.
    let node: &AbstractNode<LayoutView> = unsafe {
        transmute(&data.document_root)
    };
    ...
}

The function transmute is a cast. In this case it is converting the AbstractNode<ScriptView> to an AbstractNode<LayoutView>. The rest of the reflow deals with this so it can be proven to not access the script portions of the node and therefore should not have data races in those parts.

Node simplified

I've attempted to do a simplified example in Rust to test this type of phantom type usage. In layout.rs I have a basic Node class that is indexed over the views:

pub struct ScriptView;
pub struct LayoutView;

pub struct LayoutData {
  field3: ~str,
}

impl LayoutData {
  pub fn new() -> LayoutData {
    LayoutData { field3: ~"layoutdata" }
  }
}

pub struct Node<View> {
  field1: ~str,
  field2: ~str,

  priv layout_data: Option<@mut LayoutData>
}

Note that layout_data is private. A method implemented on Node<LayoutView> provides public access to it:

impl Node<LayoutView> {
  pub fn layout_data(&self) -> Option<@mut LayoutData> {
    self.layout_data
  }
}

Only the layout task has the LayoutView of Node so only it can get access to the layout_data method. A LayoutView is obtained by casting (using transmute):

impl<View> Node<View> {
  pub fn change_view<View>(&self) -> &Node<View> {
    unsafe {
      transmute(self)
    }
  } 
}

The file main.rc contains the main function that tests these layout types and functions:

mod layout;

pub fn main() {
  use layout::*;

  let a = ~Node::new();
  std::io::println (a.field1);
  std::io::println (a.field2);
  let b: &Node<LayoutView> = a.change_view();
  match (b.layout_data()) {
    None => { std::io::println("no layout data"); }
    Some (data) => { std::io::println(data.field3); }
  }
}

This shows accessing the fields from the ScriptView view of the Node then switching to the LayoutView to get access to the layout_data. Trying to modify the non-layout fields with the LayoutView should fail. Build the example with rustc main.rc and make sure main.rc and layout.rs are in the current directory.

The Servo code is quite a bit more complex than this but hopefully it helps with understanding the idiom of phantom type usage in nodes. If I've made any mistakes in my understanding of how things work, please let me know!

Resources

Some resources I used in writing this post:

Servo source
Rust source
Wikibooks Haskell entry for Phantom Types
Phantom Types on Haskell site
Rust tutorial
Typestate is dead post by Patrick Walton also uses phantom types.

Linking and calling Rust functions from C

2013-08-08T01:00:00+12:00

At a recent functional programming meetup I was discussing with a colleague about how nice it would be to be able to use Rust in Gecko. This made me curious if it was possible to implement libraries in Rust and call them from C. After the meeting I asked in #rust and got pointed to some projects that showed the way.

This lead me to trying to come up with as simple example as possible of compiling a Rust file into an object file, linking it to a C program and running it without the Rust runtime. The code is in my rust-from-c-example github repository. It can be cloned and built with:

$ git clone http://github.com/doublec/rust-from-c-example
$ cd rust-from-c-example
$ make
$ ./test

To avoid issues with integrating with the Rust runtime I've opted to not use it. This means no threads and limits the standard library usage. This example is very simple, only demonstrating adding two numbers. Extending from this will be an interesting exercise to see how much Rust can be used.

The Rust code is:

#[crate_type = "lib"];
#[no_std];
#[allow(ctypes)];

#[no_mangle]
pub extern fn add(lhs: uint, rhs: uint) -> uint {
  lhs + rhs
}

The first three lines ensure that the file is compiled as a library, does not use the standard library and can use C types. The no_mangle declaration stops the Rust default of mangling function names to include their module and version information. This means that add in Rust is exported as add for C programs. The extern makes the function available from C and defaults to cdecl calling format.

To generate a .o file that can be linked into a C program:

$ rustc -c mylib.rs

The C program creates an extern declaration for add and calls it:

#include <stdio.h>

extern unsigned int add(unsigned int lhs, unsigned int rhs);

int main() {
  printf("add(40,2) = %u\n", add(40,2));
  return 0;
}

Unfortunately we can't just compile and link with the mylib.o file. This results in a linker error:

mylib.o: In function `add':
mylib.rc:(.text+0x4f): undefined reference to `upcall_call_shim_on_rust_stack'
collect2: error: ld returned 1 exit status

Some searching pointed me to armboot which had a stub implementation for this in zero.c. Compiling and linking to that worked successfully. A cut down variant of zero.c is included in the project.

There's a bunch of limitations with this approach. We're basically using Rust as a higher level C. This post on embedding Rust in Ruby details some of the limitations:

When calling Rust code you will not be executing in a Rust task and will not have access to any runtime services that require task-local resources. Currently this means you can't use the local heap, nor can you spawn or communicate with tasks, nor call fail!() to unwind the stack. I/O doesn't work because core::io (unfortunately, and incorrectly) uses @-boxes. Even logging does not work. Calling any code that tries to access the task context will cause the process to abort. Because code is not executing in a task, it does not grow the stack, and instead runs on whatever stack the foreign caller was executing on. Recurse too deep and you will scribble on random memory.

Hopefully some of these limitations will go away or 'zero runtime' libraries will appear to make this sort of usage easier. Some resources that helped putting this together were:

Building Rust

2011-10-24T18:00:00+13:00

Update 2011-11-08 - The steps to build Rust have changed since I wrote this post, there's now no need to build LLVM - it's included as a submodule in the Rust git repository and will automatically be cloned and built.

A while ago I wrote a quick look at Rust post, describing how to build it and run some simple examples. Since that post the bootstrap compiler has gone away and the rustc compiler, written in Rust, is the compiler to use.

The instructions for building Rust in the wiki are good but I'll briefly go through how I installed things on 64-bit Linux. The first step is to build the required version of LLVM from the LLVM source repository. I use a git mirror and install to a local directory so as not to clash with other programs that use older LLVM versions.

$ git clone git://github.com/earl/llvm-mirror.git
$ cd llvm-mirror
$ git reset --hard 9af578
$ CXX='g++ -m32' CC='gcc -m32' CFLAGS=-m32 CXXFLAGS=-m32 LDFLAGS=-m32 ./configure \
    --{build,host,target}=i686-unknown-linux-gnu \
    --enable-targets=x86,x86_64,cbe --enable-optimized --prefix=/home/chris/rust
$ make && make install

Note the use of prefix to ensure this custom LLVM build is a local install. I also do a git reset to go to the commit for SVN revision 142082 which is the current version that works with Rust according to the wiki. After installation add the install bin to the PATH and lib to LD_LIBRARY_PATH:

$ export PATH=~/rust/bin:$PATH
$ export LD_LIBRARY_PATH=~/rust/lib:$LD_LIBRARY_PATH

Next step, clone and build Rust:

$ git clone git://github.com/graydon/rust
$ mkdir build
$ cd build
$ ../rust/configure
$ make

The build process downloads an existing build for your platform to bootstrap from. It uses this to build a stage1 version of the compiler. This stage1 is used to build a stage2, and that is then used to build a stage3. All the built compilers should work exactly the same if things are working correctly. The compiler can be run within the build directory, or outside it if you put the stage3/bin directory in the path:

$ export PATH=~/path/to/build/stage3/bin:$PATH
$ rustc
error: No input filename given.

Test with a simple 'hello world' program:

$ cat hello.rs
use std;
import std::io::print;

fn main () {
  print ("hello\n");
}
$ rustc hello.rs
$ ./hello
hello

A Quick Look at the Rust Programming Language

2011-03-31T20:00:00+13:00

The Rust Programming Language is a systems programming language being developed by Mozilla. It was announced last year and has seen quite a bit of development since then.

I've only been lightly following the development over the past year but recently decided to spend a bit more time looking at it. The following is a look at the language and implementation from someone who isn't heavily involved in the development so don't take anything I write as gospel. Hopefully I don't get too many things wrong.

The Rust Language FAQ lists the following summary of features:

Memory safe. No null pointers, wild pointers, etc. Automatic storage management.
Mutability control. Immutable by default. No shared mutable state across tasks.
Dynamic execution safety: task failure / unwinding, trapping, logging. RAII / dtors.
Typestate system: ability to define complex invariants that hold over data structures.
Explicit memory control. Layout and allocation control. Interior / value types.
Very lightweight tasks (coroutines). Cheap to spawn thousands-to-millions.
Stack iterators (effectively lambda-blocks w/o heap allocation).
Static, native compilation. Emits ELF / PE / Mach-o files.
Direct and simple interface to C code (switch stacks and call, ~8 insns).
Multi-paradigm. pure-functional, concurrent-actor, imperative-procedural, OO.
First class functions with bindings.
Structurally-typed objects (no nominal types or type hierarchy).
Multi-platform. Developed on Windows, Linux, OSX.
UTF8 strings, assortment of machine-level types.
Works with existing native toolchains. GDB / Valgrind / Shark / etc.
Practical rule-breaking: can break safety rules, if explicit about where and how.

The Rust implementation is still in the 'only useful for Rust developers' state since the implementation and libraries are still being developed. There are two Rust compilers in various states of development. They are:

rustboot - written in O'Caml with it's own x86 code generation backend. This is being used to bootstrap the 'rustc' implementation.
rustc - self hosting compiler written in Rust and bootstrapped using 'rustbost'. Code generation is done using LLVM.

rustboot can be used to write Rust programs and try out the language. rustc is still in heavy development and only very basic stuff works from what I can see.

Building

Please note, as of 2011-10-24, the instructions for building Rust below are out of date. For updated instructions read my recent post on building Rust.

The instructions to build Rust are in the wiki. One important point is you need an SVN version of LLVM. I built this from source using a git mirror of LLVM (on 64 bit x86 Linux):

$ git clone git://github.com/earl/llvm-mirror.git
$ cd llvm-miror
~/llvm-mirror $ CXX='g++ -m32' CC='gcc -m32' CFLAGS=-m32 CXXFLAGS=-m32 \
                LDFLAGS=-m32 ./configure --enable-shared --disable-bindings \
                 --{build,host,target}=i686-unknown-linux-gnu \
                 --enable-targets=x86,x86_64,cbe
~/llvm-mirror $ make && make install

Once you have LLVM and the other pre-requisites installed:

$ git clone git://github.com/graydon/rust.git
$ cd rust
~/rust $ mkdir build
~/rust $ cd build
~/rust/build $ ../configure
~/rust/build $ make check

This builds the rustboot compiler, uses that to compile rustc, then runs a series of tests using both builds. If you have valgrind installed this will be slow as the tests are run under valgrind.

Bootstrap Compiler

The bootstrap compiler executable is boot/rustboot. The command to execute it, assuming the build occurred in the directory ~/rust/build is:

~/rust/build $ OCAMLRUNPARAM="b1" boot/rustboot -L boot -o hello hello.rs

This will compile a Rust program in hello.rs and leave an executable hello. The -L argument references the boot subdirectory containing the Rust standard library in libstd.so. A 'hello world' program for testing is:

use std;

fn main() {
  log "Hello World";
}

To run the executable you'll need to adjust the LD_LIBRARY_PATH to include the rt subdirectory to pick up the Rust runtime shared library:

~/rust/build $ OCAMLRUNPARAM="b1" boot/rustboot -L boot -o test test.rs
~/rust/build $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:~/rust/build/rt
~/rust/build $ ./hello
rt: ---
rt: ca09:main:main: rust: Hello World

rustc Compiler

The rustc compiler lives in stage0/rustc. The output of this compiler is LLVM bytecode which must then be compiled using LLVM tools. To compile the hello.rs program mentioned in the previous section:

~/rust/build $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:~/rust/build/rt:~/rust/build/rustllvm
~/rust/build $ stage0/rustc -nowarn -L stage0 -o hello.bc hello.rs
~/rust/build $ llc -march=x86 -relocation-model=pic -o hello.s hello.bc
~/rust/build $ gcc -fPIC -march=i686 -m32 -fno-rtti -fno-exceptions -g \
               -o hello.o -c hello.s
~/rust/build $ gcc -fPIC -march=i686 -m32 -fno-rtti -fno-exceptions -g \
               stage0/glue.o -o hello hello.o -Lstage0 -Lrt -lrustrt

Note the need to add the rustllvm directory to LD_LIBRARY_PATH to pick up a shared library. That sequence of commands will compile the hello.rs file to LLVM bytecode. llc compiles the bytecode to x86 assembly. gcc compiles this to an object file, followed by a final gcc invocation to link it. And to run:

~/rust/build $ ./hello
rt: ---
rt: ee0b:main:main: rust: Hello World

Rust Language Details

For examples of the Rust language there are multiple tests and the source code to rustc itself in the github repository. The wiki has a link to the PDF documentation, currently a snapshot from 2011-02-25.

The following are some quick examples of Rust features that work with the bootstrap compiler.

Foreign Function Interface

This program uses the C FFI to call the 'puts' function from the C shared library:

use std;
import std._str.rustrt.sbuf;
import std._str;

native mod libc = "libc.so.6" {
    fn puts(sbuf s) -> int;
}

unsafe fn main() {
  libc.puts(_str.buf("hello from C\n"));
}

Compile and run with:

~/rust/build $ OCAMLRUNPARAM="b1" boot/rustboot -L boot -o cffi cffi.rs
~/rust/build $ ./cffi
hello from C

Command Line Arguments

use std;

fn main(vec[str] args) {
  for(str s in args) {
    log s;
  }
}

The main function takes a vector of strings as the argument. This holds the command line arguments passed to the program. The example iterates over the vector printing out each element.

~/rust/build $ OCAMLRUNPARAM="b1" boot/rustboot -L boot -o args args.rs
~/rust/build $ ./args a b c
rt: ---
rt: ccca:main:main: rust: ./args
rt: ccca:main:main: rust: a
rt: ccca:main:main: rust: b
rt: ccca:main:main: rust: c

Factorial

use std;

fn fac(uint x) -> uint {
  if (x <= 1u) {
    ret 1u;
  }
  else {
    ret x * fac(x-1u);
  }
}

fn main() {
  log fac(5u);
}

No language is complete without showing how factorial can be computed.

~/rust/build $ ./fac
rt: ---
rt: d158:main:main: rust: 120 (0x78)

Spawning Tasks

use std;

impure fn logger(port[str] logs) {
  let int i = 0;
  while (i < 2) {
    auto msg <- logs;
    log msg;
    i = i + 1;
  }
  log "logger exited";
}

impure fn main() {
  let port[str] logs = port();
  let task p = spawn logger(logs);
  auto out = chan(logs);
  out <| "Hello";
  out <| "World";
  join p;
}

A port is the receiving end of a typed inter task communication mechanism. A channel is the sending end of the communication mechanism. <| sends to the port and <- receives from the channel.

~/rust/build $ OCAMLRUNPARAM="b1" boot/rustboot -L boot -o spawn spawn.rs
~/rust/build $ ./spawn
rt: ---
rt: 9a73:main:spawn.rs:1: rust: Hello
rt: 9a73:main:spawn.rs:1: rust: World
rt: 9a73:main:spawn.rs:1: rust: logger exited

Types

use std;

tag list {
  nil;
  cons(int, @list);
}

fn list_len(@list l) -> uint {
   fn len(@list l, &uint n) -> uint {
    alt (*l) {
      case (nil) {
        ret n;
      }
      case (cons(_, ?xs)) {
        ret len(xs, n+1u);
      }
    }
  }
  ret len(l, 0u);
}

fn main() {
  let @list l = @cons(1, @cons(2, @cons(3, @nil)));
  log list_len(l);
}

This example creates a list type. It has constructors for an empty list, nil, and a cons containing an integer and the rest of the list. The '@' prefixed to the list type in places means that that variable holds a boxed object. That is, it's a reference-counted heap allocation.

The list_len function shows the use of a local function which pattern matches over the list (using the alt keyword) and keeps a running total of the list length. The main function creates a list and prints the length.

~/rust/build $ OCAMLRUNPARAM="b1" boot/rustboot -L boot -o types types.rs
~/rust/build $ ./types
rt: ---
rt: 8126:main:main: rust: 3 (0x3)

Typestate

The typestate system is one of the things that most interests me about Rust. If you've been reading my ATS posts, in particular the ones involving type safe checking of array bounds, you'll know I'm interested in languages that can help with detecting programming problems at compile time. It seems to me that the typesafe system can help here.

Here's a contrived example demonstrating one use of typestate. main takes a vector of strings containing the command line arguments. I want to call a function, dosomething, that will use these arguments but for some reason there must be never more than 2 arguments. Imagine I'm calling some C routine that'll die if I do.

I could check at runtime that the number of arguments is less than three. Here's an example that does this:

use std;
import std._vec;

fn dosomething(&vec[str] args) {
  log "vector length is less than 3";
}

fn main(vec[str] args) {
  log _vec.len[str](args);
  check (_vec.len[str](args) < 3u);
  dosomething(args);
}

Some example runs:

~/rust/build $ OCAMLRUNPARAM="b1" boot/rustboot -L boot -o ts1 ts1.rs
~/rust/build $ ./ts1 a
rt: ---
rt: b3b1:main:main: rust: 2 (0x2)
rt: b3b1:main:main: rust: vector length is less than 3
~/rust/build $ ./ts1 a b
rt: ---
rt: d884:main:main: rust: 3 (0x3)
rt: d884:main:main: upcall fail '.t0 < 3u', ts2.rs:5

Notice the last invocation has failed since three arguments are used (the program name is counted as an argument).

It would be good to be able to check at compile time that somewhere the assertion holds that the number of arguments is less than three. In our example if we left the check call out, the program would still compile, but dosomething might do something disasterous. We can tell the typestate system that the precondition must hold for callers of dosomething and to fail at compile time by adding a 'prove statement' to the function:

use std;
import std._vec;

fn prove_length(&vec[str] args, uint n) -> bool {
  ret _vec.len[str](args) < n;
}

fn dosomething(&vec[str] args) : prove_length(args, 3u) {
  log "vector length is less than 3";
}

fn main(vec[str] args) {
  log _vec.len[str](args);
  dosomething(args);
}

The addition of : prove_length(args, 3u) to the function tells the typestate system that this boolean function must evaluate to true. It examines what it knows of the constraints made via check statements and the like to see if it can prove that this is the case. If it is not then a compile error occurs. The above program will fail to compile:

~/rust/build $ OCAMLRUNPARAM="b1" boot/rustboot -L boot -o ts2 ts2.rs
ts2.rs:14:13:14:19: error: Unsatisfied precondition constraint prove_length(args, 3u)

If we add a check statement we are adding an assertion check that this precondition holds. Typestate makes note of this and will now allow that call to dosomething to compile:

use std;
import std._vec;

fn prove_length(&vec[str] args, uint n) -> bool {
  ret _vec.len[str](args) < n;
}

fn dosomething(&vec[str] args) : prove_length(args, 3u) {
  log "vector length is less than 3";
}

fn main(vec[str] args) {
  log _vec.len[str](args);
  check prove_length(arg, 3u);
  dosomething(args);
}

~/rust/build $ OCAMLRUNPARAM="b1" boot/rustboot -L boot -o ts3 ts3.rs
~/rust/build $ ./ts3
rt: ---
rt: d9e6:main:main:                       rust: 1 (0x1)
rt: d9e6:main:main:                       rust: vector length is less than 3

It'll be interesting to see how typestate is used in the standard library and third party libraries to help with compile time checking of code.

Conclusion

Rust is an interesting language and there's quite a bit more to it than I've covered here. I just picked random features to try. I'm looking forward to rustc being more complete and trying out some of the language features in more 'real world' examples to get a feel for it.