Note getting started developing Rust

This page describes how to download and build the Rust compiler and associated tools and libraries from the current git sources. If you're more interested in using Rust than in hacking on the Rust compiler, you might prefer to install a prebuilt snapshot from here, following the instructions in the tutorial. For Windows users, see Using Rust on Windows.

Prerequisites

Version numbers listed here are "what we're using"; the code may well work with earlier versions of these tools, but we don't know minimum version requirements.

• A recent Linux, OS X (10.6 or later), Win32 or FreeBSD system
• 1.5 GiB RAM available for the build process (see note below about memory usage)
• python 2.x (version 2.7 is known to work)
• GNU make 3.81
• git 1.7
• g++ 4.7 at least on Linux, 4.5 on Windows, and the 4.x gcc in Apple's SDK for OS X.
• curl
• recommended: valgrind 3.8.0 or later (not required for Linux)
• optional: if you wish to build LaTeX PDF docs, pandoc 1.9.1 at least, with one or more of pdflatex/xelatex/lualatex
• optional: ccache to shorten your rebuild times

Memory usage

The Rust build peaks at around 1.3 GiB, so at least that much memory should be available for the build in order to avoid excessive swapping or out-of-memory. If you only have 2 GiB of RAM total, you may have a difficult time building Rust while doing anything else, such as using a browser.

Note that if you are compiling Rust from within a virtual OS (e.g. via Vagrant) you may need to change how much RAM your VM has access to.

Debian-based Linux Distributions

You can install all the prerequisites you need to build Rust by running:

sudo apt-get install python make git g++ curl valgrind

For Ubuntu users willing to build LaTeX doc, you will need some more packages:

sudo apt-get install pandoc texlive-latex-recommended lmodern

The pandoc that's packaged with certain Linux distributions (Ubuntu, for instance) is sometimes quite old, so make sure that it's at least version 1.9.1 (you can check the version by running pandoc -V). If your version's too old, follow the building instructions here.
Also, make sure you have the lmodern font package (see #3989).

Windows

The Rust build system depends on a UNIX shell environment, so you'll need MSYS, which provides such an environment on Windows. We currently recommend MSYS2, which also provides a convenient package manager. You can install the compiler toolchain using MSYS2's package manager.

(MSYS1 is fine if you already have it, but configuring MSYS1 is not an easy job. Also beware of MSYS1 bugs such as make -jN freezing randomly.)

MSYS2 provides three environments: mingw32_shell.bat, mingw64_shell.bat and msys2_shell.bat. For the Rust build you should select correct batch file described below.

32-bit build

Execute mingw32_shell.bat to run MSYS2 for a 32-bit system. Run the following commands:

pacman -S mingw-w64-i686-toolchain
pacman -S base-devel

To check the installation was successful, type gcc -v. The target should be i686-w64-mingw32.

Now everything is ready, cd into the Rust source directory and run:

./configure
make

This will start the Rust build.

64-bit build

Execute mingw64_shell.bat to run MSYS2 for a 64-bit system. Run the following commands:

pacman -S mingw-w64-x86_64-toolchain
pacman -S base-devel

To check the installation was successful, type gcc -v. The target should be i686-w64-mingw32.

OSX

Get the command line tools for Xcode from Apple Developer Downloads, or open Xcode and go to Xcode -> Preferences -> Downloads -> Components.

Then optionally install Valgrind and pandoc. Valgrind is available from homebrew: brew install valgrind. pandoc must be installed manually according to the installation instructions. ccache can also be installed from homebrew: brew install ccache.

Sometimes, on OS X, compiling Rust might fail with a "too many open files" error, especially when running make check.

• One solution is to limit the number of concurrent threads during the run, via the environment variable RUST_THREADS, e.g. % RUST_THREADS=2 make check.
• Another solution for this is to raise the open file limit on OS X. One method to achieve this (that has been tested on 10.7.5) is the following:

1. Raise the number of maximum files allowed on the system: sudo sysctl -w kern.maxfiles=1048600 and sudo sysctl -w kern.maxfilesperproc=1048576. This can be made persistent by adding the following lines to /etc/sysctl.conf:

kern.maxfiles=1048600
kern.maxfilesperproc=1048576

2. Raise the launchd limits: sudo launchctl limit maxfiles 1048576. Can be made persistent by adding limit maxfiles 1048576 to /etc/launchd.conf.

3. Verify the changes. If all goes well, sudo launchctl limit should show something like this:

  [...]
  maxproc     709            1064
  maxfiles    1048575        1048575

4. Run the compiler. Note that if the changes aren't made persistent, you need to run as root, since the per-user launchd won't inherit the settings. If you do change the config files, you need to reboot to apply the appropriate settings.

FreeBSD

Rust will build on FreeBSD, but it's not officially supported. Building is only known to work on 9.0-RELEASE. You'll need some prerequisites, which you can install with:

pkg_add -r git gmake libexecinfo libunwind

The gcc included with FreeBSD is old, so your best bet is to run the configure script with --enable-clang (i.e. ./configure --enable-clang). Installing gcc 4.6 can also work. Build with gmake instead of make.

Android

See building for Android

Downloading and Building Rust

Before you get started, you should quickly review the build system notes which describes the Make targets, among other things.

git clone git://github.com/mozilla/rust.git
cd rust
./configure   # this may take a while if this is your first time, as it downloads LLVM

If you already have one of the prerequisites installed, like Python or Perl, make sure the PATH environment variable is set so the configure script can find it, otherwise you will get errors during configure.

make    # this will definitely take a while if this is your first time, as it builds LLVM

Optional steps:

make check   # Run the test suite. On windows, `make check` may not pass. In any case, `make check-fast` should work (see #4193)
make install   # Install the compiler and associated tools

This will build and test the compiler, standard libraries, and supporting tools.

Note: You can use make -j8 (if you have an 8-core machine) to speed up the build (or at least the LLVM part and the tests). On Linux or OS X, if you have Valgrind installed, the tests will run slowly because they are running under Valgrind. If you define CFG_DISABLE_VALGRIND=1 in your build environment or run configure with the --disable-valgrind flag, you can see the tests running at full speed.

Note: If you need to pass in extra flags to make, you can add RUSTFLAGS=... to the argument list for make. For example, make check RUSTFLAGS="-Z debug-info" builds the compiler and runs tests with debug info enabled.

Note: Some make targets are only exercised by make check-full. If you want to see what commands a make invocation is running, you can add VERBOSE=1 to the argument list for make. Also, if you use make options like --print-data-base to see other targets, note that some rules in the database are only generated dynamically. See also: Build system notes

Navigating

There's a quick guide to the source of the compiler in src/librustc/README.txt. You should look through it if you're planning on contributing.

Editor support

Syntax highlighting for vim and emacs is included in the Rust repository. For vim, the files are under src/etc/vim, and for emacs they're under src/etc/emacs. Other editors may also be supported.

The issue tracker

We use the GitHub issue tracker to track bugs and feature requests in Rust. If you prefer not to use the standard GitHub issue tracker, there's a secondary front-end that is quite a bit more responsive.

Communicating

Join irc.mozilla.org #rust for real-time discussion of Rust development. We try to remain on that channel during working hours in UTC-7 (US Pacific).

Join the mailing list for longer conversations.

In both cases, please follow the conduct guidelines on the development policy.