[rustc.git] / README.md

# The Rust Programming Language

This is a compiler for Rust, including standard libraries, tools and
documentation.

## Quick Start

1. Download a [binary installer][installer] for your platform.
2. Read [The Rust Programming Language][trpl].
3. Enjoy!

> ***Note:*** Windows users can read the detailed
> [using Rust on Windows][win-wiki] notes on the wiki.

[installer]: http://www.rust-lang.org/install.html
[trpl]: http://doc.rust-lang.org/book/index.html
[win-wiki]: https://github.com/rust-lang/rust/wiki/Using-Rust-on-Windows

## Building from Source

1. Make sure you have installed the dependencies:
    * `g++` 4.7 or `clang++` 3.x
    * `python` 2.6 or later (but not 3.x)
    * `perl` 5.0 or later
    * GNU `make` 3.81 or later
    * `curl`
    * `git`
2. Download and build Rust:

    You can either download a [tarball] or build directly from the [repo].

    To build from the [tarball] do:

        $ curl -O https://static.rust-lang.org/dist/rust-nightly.tar.gz
        $ tar -xzf rust-nightly.tar.gz
        $ cd rust-nightly

    Or to build from the [repo] do:

        $ git clone https://github.com/rust-lang/rust.git
        $ cd rust

    Now that you have Rust's source code, you can configure and build it:

        $ ./configure
        $ make && make install

    > ***Note:*** You may need to use `sudo make install` if you do not normally have
    > permission to modify the destination directory. The install locations can
    > be adjusted by passing a `--prefix` argument to `configure`. Various other
    > options are also supported, pass `--help` for more information on them.

    When complete, `make install` will place several programs into
    `/usr/local/bin`: `rustc`, the Rust compiler, and `rustdoc`, the
    API-documentation tool.
3. Read [The Rust Programming Language][trpl].
4. Enjoy!

### Building on Windows

To easily build on windows we can use [MSYS2](http://sourceforge.net/projects/msys2/):

1. Grab the latest MSYS2 installer and go through the installer.
2. Now from the MSYS2 terminal we want to install the mingw64 toolchain and the other
   tools we need.

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

3. With that now start `mingw32_shell.bat` from where you installed MSYS2 (i.e. `C:\msys`).
4. From there just navigate to where you have Rust's source code, configure and build it:

        $ ./configure
        $ make && make install

[repo]: https://github.com/rust-lang/rust
[tarball]: https://static.rust-lang.org/dist/rust-nightly.tar.gz
[trpl]: http://doc.rust-lang.org/book/index.html

## Notes

Since the Rust compiler is written in Rust, it must be built by a
precompiled "snapshot" version of itself (made in an earlier state of
development). As such, source builds require a connection to the Internet, to
fetch snapshots, and an OS that can execute the available snapshot binaries.

Snapshot binaries are currently built and tested on several platforms:

* Windows (7, 8, Server 2008 R2), x86 and x86-64 (64-bit support added in Rust 0.12.0)
* Linux (2.6.18 or later, various distributions), x86 and x86-64
* OSX 10.7 (Lion) or greater, x86 and x86-64

You may find that other platforms work, but these are our officially
supported build environments that are most likely to work.

Rust currently needs about 1.5 GiB of RAM to build without swapping; if it hits
swap, it will take a very long time to build.

There is a lot more documentation in the [wiki].

[wiki]: https://github.com/rust-lang/rust/wiki

## Getting help and getting involved

The Rust community congregates in a few places:

* [StackOverflow] - Get help here.
* [/r/rust] - General discussion.
* [discuss.rust-lang.org] - For development of the Rust language itself.

[StackOverflow]: http://stackoverflow.com/questions/tagged/rust
[/r/rust]: http://reddit.com/r/rust
[discuss.rust-lang.org]: http://discuss.rust-lang.org/

## License

Rust is primarily distributed under the terms of both the MIT license
and the Apache License (Version 2.0), with portions covered by various
BSD-like licenses.

See LICENSE-APACHE, LICENSE-MIT, and COPYRIGHT for details.
Commit	Line	Data
223e47cc LB	1	# The Rust Programming Language
	2
	3	This is a compiler for Rust, including standard libraries, tools and
	4	documentation.
	5
1a4d82fc	6	## Quick Start
223e47cc	7
1a4d82fc JJ	8	1. Download a [binary installer][installer] for your platform.
	9	2. Read [The Rust Programming Language][trpl].
	10	3. Enjoy!
223e47cc	11
1a4d82fc JJ	12	> *Note:* Windows users can read the detailed
1a4d82fc JJ	13	> [using Rust on Windows][win-wiki] notes on the wiki.
223e47cc	14
1a4d82fc JJ	15	[installer]: http://www.rust-lang.org/install.html
	16	[trpl]: http://doc.rust-lang.org/book/index.html
	17	[win-wiki]: https://github.com/rust-lang/rust/wiki/Using-Rust-on-Windows
223e47cc	18
1a4d82fc	19	## Building from Source
223e47cc	20
1a4d82fc JJ	21	1. Make sure you have installed the dependencies:
	22	* `g++` 4.7 or `clang++` 3.x
	23	* `python` 2.6 or later (but not 3.x)
	24	* `perl` 5.0 or later
	25	* GNU `make` 3.81 or later
	26	* `curl`
	27	* `git`
	28	2. Download and build Rust:
223e47cc	29
1a4d82fc JJ	30	You can either download a [tarball] or build directly from the [repo].
	31
	32	To build from the [tarball] do:
	33
	34	$ curl -O https://static.rust-lang.org/dist/rust-nightly.tar.gz
	35	$ tar -xzf rust-nightly.tar.gz
	36	$ cd rust-nightly
	37
	38	Or to build from the [repo] do:
	39
	40	$ git clone https://github.com/rust-lang/rust.git
	41	$ cd rust
	42
	43	Now that you have Rust's source code, you can configure and build it:
223e47cc	44
1a4d82fc JJ	45	$ ./configure
1a4d82fc JJ	46	$ make && make install
223e47cc	47
1a4d82fc JJ	48	> *Note:* You may need to use `sudo make install` if you do not normally have
	49	> permission to modify the destination directory. The install locations can
	50	> be adjusted by passing a `--prefix` argument to `configure`. Various other
	51	> options are also supported, pass `--help` for more information on them.
223e47cc	52
1a4d82fc JJ	53	When complete, `make install` will place several programs into
	54	`/usr/local/bin`: `rustc`, the Rust compiler, and `rustdoc`, the
	55	API-documentation tool.
	56	3. Read [The Rust Programming Language][trpl].
	57	4. Enjoy!
223e47cc	58
1a4d82fc	59	### Building on Windows
223e47cc	60
1a4d82fc	61	To easily build on windows we can use [MSYS2](http://sourceforge.net/projects/msys2/):
223e47cc	62
1a4d82fc JJ	63	1. Grab the latest MSYS2 installer and go through the installer.
	64	2. Now from the MSYS2 terminal we want to install the mingw64 toolchain and the other
	65	tools we need.
223e47cc	66
1a4d82fc JJ	67	$ pacman -S mingw-w64-i686-toolchain
1a4d82fc JJ	68	$ pacman -S base-devel
223e47cc	69
1a4d82fc JJ	70	3. With that now start `mingw32_shell.bat` from where you installed MSYS2 (i.e. `C:\msys`).
	71	4. From there just navigate to where you have Rust's source code, configure and build it:
	72
	73	$ ./configure
	74	$ make && make install
	75
	76	[repo]: https://github.com/rust-lang/rust
	77	[tarball]: https://static.rust-lang.org/dist/rust-nightly.tar.gz
	78	[trpl]: http://doc.rust-lang.org/book/index.html
	79
	80	## Notes
	81
	82	Since the Rust compiler is written in Rust, it must be built by a
	83	precompiled "snapshot" version of itself (made in an earlier state of
	84	development). As such, source builds require a connection to the Internet, to
	85	fetch snapshots, and an OS that can execute the available snapshot binaries.
	86
	87	Snapshot binaries are currently built and tested on several platforms:
223e47cc	88
1a4d82fc JJ	89	* Windows (7, 8, Server 2008 R2), x86 and x86-64 (64-bit support added in Rust 0.12.0)
	90	* Linux (2.6.18 or later, various distributions), x86 and x86-64
	91	* OSX 10.7 (Lion) or greater, x86 and x86-64
	92
	93	You may find that other platforms work, but these are our officially
	94	supported build environments that are most likely to work.
	95
	96	Rust currently needs about 1.5 GiB of RAM to build without swapping; if it hits
	97	swap, it will take a very long time to build.
	98
	99	There is a lot more documentation in the [wiki].
	100
	101	[wiki]: https://github.com/rust-lang/rust/wiki
	102
	103	## Getting help and getting involved
	104
	105	The Rust community congregates in a few places:
	106
	107	* [StackOverflow] - Get help here.
	108	* [/r/rust] - General discussion.
	109	* [discuss.rust-lang.org] - For development of the Rust language itself.
	110
	111	[StackOverflow]: http://stackoverflow.com/questions/tagged/rust
	112	[/r/rust]: http://reddit.com/r/rust
	113	[discuss.rust-lang.org]: http://discuss.rust-lang.org/
223e47cc LB	114
	115	## License
	116
	117	Rust is primarily distributed under the terms of both the MIT license
	118	and the Apache License (Version 2.0), with portions covered by various
	119	BSD-like licenses.
	120
	121	See LICENSE-APACHE, LICENSE-MIT, and COPYRIGHT for details.