├── Doc-FAQ-Cheatsheet.md ├── .gitignore ├── Doc-language-faq.md ├── Games-written-in-Rust.md ├── Note-style-guide.md ├── Note Building Rust Before 0.8 on Windows Systems.md ├── Doc how to install an unofficial nightly for Windows.md ├── Howto-submit-a-rust-bug-report.md ├── Note-rustc-hacking-guide---back-end.md ├── Doc-vim-support.md ├── _Sidebar.md ├── Note-buildbots.md ├── Docs-project-structure.md ├── Note-rustc-hacking-guide---middle-end.md ├── Note-rustc-hacking-guide.md ├── Doc-examples.md ├── Libs.md ├── Home.md ├── Doc-lowlevel-details.md ├── Doc continuous integration.md ├── Meeting-RFC-triage-2014-06-19.md ├── IRC-notifications-channel.md ├── Sigil-reference.md ├── Doc-building-for-ios.md ├── Note-wiki-conventions.md ├── Note-rustc-hacking-guide---front-end.md ├── Note-Intrinsics.md ├── Note-core-team.md ├── Community-User-Groups,-Meetups,-and-Events.md ├── lib-template.md ├── Note-code-review.md ├── Note-operator-overloading.md ├── Notes.md ├── Projects-using-Rust.md ├── Mixed-language-link-time-optimization.md ├── Using-Rust-on-Windows.md ├── Teaching-Rust.md ├── Note-Rust-performance-fixes.md ├── Note-bors-usage.md ├── Note-seeing-LLVM-output-from-rust.md ├── Operating-system-development.md ├── Doc-Emacs-Support.md ├── Lib-html.md ├── Lib-fmt.md ├── Meeting-API-review-2014-06-23.md ├── OS-Bridge-2013-tutorial.md ├── Note-guide-for-new-contributors.md ├── Anticipated-breaking-changes-during-1.0-alpha.md ├── Doc-under-construction-FAQ.md ├── Rustpkg-schedule.md ├── Note-research.md ├── Doc-packages,-editors,-and-other-tools.md ├── Note-git-workflow.md ├── Note-compiler-snapshots.md ├── Docs.md ├── Note-priority-issue-criteria.md ├── Lib-simd.rest ├── Note-0.5-priorities.md ├── Note-tag-label-names-and-definitions.md ├── Lib-io.md ├── Lib-rand.md ├── The-Rusticon.md ├── Library-editing.md ├── Note-getting-started-developing-Rust.md ├── Doc-friends-of-the-tree.md ├── Note-testsuite.md └── Doc-building-for-android.md /Doc-FAQ-Cheatsheet.md: -------------------------------------------------------------------------------- 1 | See http://rustbyexample.com/ -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | *~ 2 | \#*\# 3 | \#* 4 | .#* 5 | *.html 6 | -------------------------------------------------------------------------------- /Doc-language-faq.md: -------------------------------------------------------------------------------- 1 | See [[http://static.rust-lang.org/doc/master/complement-lang-faq.html]] -------------------------------------------------------------------------------- /Games-written-in-Rust.md: -------------------------------------------------------------------------------- 1 | See [[Computer-Graphics-and-Game-Development#game-projects]] 2 | -------------------------------------------------------------------------------- /Note-style-guide.md: -------------------------------------------------------------------------------- 1 | These have been moved to [the Rust guidelines](http://aturon.github.io/) -------------------------------------------------------------------------------- /Note Building Rust Before 0.8 on Windows Systems.md: -------------------------------------------------------------------------------- 1 | (This is obsolete; see [[Note-getting-started-developing-Rust]].) -------------------------------------------------------------------------------- /Doc how to install an unofficial nightly for Windows.md: -------------------------------------------------------------------------------- 1 | (This is obsolete; see [[Note-getting-started-developing-Rust]].) -------------------------------------------------------------------------------- /Howto-submit-a-rust-bug-report.md: -------------------------------------------------------------------------------- 1 | [This page has moved](http://static.rust-lang.org/doc/master/complement-bugreport.html) -------------------------------------------------------------------------------- /Note-rustc-hacking-guide---back-end.md: -------------------------------------------------------------------------------- 1 | The back end includes files that handle linking, name mangling, and the ABI. It lives in ```src/librustc/back```. -------------------------------------------------------------------------------- /Doc-vim-support.md: -------------------------------------------------------------------------------- 1 | Vim plugin has moved to its own repository. See [rust-lang/rust.vim](https://github.com/rust-lang/rust.vim) for instruction on how to install. -------------------------------------------------------------------------------- /_Sidebar.md: -------------------------------------------------------------------------------- 1 | All Categories: 2 | 3 | * [[Docs]] -- For users 4 | * [[Notes]] -- For developers 5 | * [[Libs]] -- For library authors 6 | * [Meeting minutes](https://github.com/rust-lang/meeting-minutes) -------------------------------------------------------------------------------- /Note-buildbots.md: -------------------------------------------------------------------------------- 1 | There is a very handy buildbot service at http://buildbot.rust-lang.org/. It, guided by [bors](https://github.com/bors), builds all reviewed pull requests, and merges them if tests pass. 2 | 3 | The current platforms are: 4 | 5 | ```txt 6 | Linux (Ubuntu 12.04 LTS and CentOS 6, x86 and x64) 7 | OS X Lion (10.7.4, x86 and x64) 8 | FreeBSD 9 (x64) 9 | Windows Server 2008R2 (x86) 10 | ``` -------------------------------------------------------------------------------- /Docs-project-structure.md: -------------------------------------------------------------------------------- 1 | Project structure in Rust is pretty free-form. The current convention is to have all source code in a `src/` directory. `src/lib.rs` is the crate root for libraries and `src/main.rs` is the crate root for executables. 2 | 3 | Examples go in `src/examples` and out-of-crate tests (*not* using the [built-in unit testing](http://static.rust-lang.org/doc/master/guide-testing.html)) go in `src/tests`. -------------------------------------------------------------------------------- /Note-rustc-hacking-guide---middle-end.md: -------------------------------------------------------------------------------- 1 | The middle end includes the resolver, typechecker, kind checker, typestate checker, and various other semantic analysis passes. The source files for it live in ```src/librustc/middle```. The middle end also includes the code generator that generates LLVM code from Rust abstract syntax tree: the code generator files are in ```src/librustc/middle/trans```. 2 | 3 | * [[Note Intrinsics]] -------------------------------------------------------------------------------- /Note-rustc-hacking-guide.md: -------------------------------------------------------------------------------- 1 | This is a collection of pages intended to help new hackers learn their way around the internals of the Rust compiler. It will probably always be incomplete. Please help by extending and adding pages as you learn new things about the compiler. 2 | 3 | * [Front end](Note rustc hacking guide - Front end) 4 | * [Middle end](Note rustc hacking guide - Middle end) 5 | * [Back end](Note rustc hacking guide - Back end) 6 | 7 | Also: 8 | * [A More Detailed Tour of the Rust Compiler](http://tomlee.co/2014/04/03/a-more-detailed-tour-of-the-rust-compiler/) -------------------------------------------------------------------------------- /Doc-examples.md: -------------------------------------------------------------------------------- 1 | There isn't a single comprehensive repository of Rust examples yet, but here are a few resources. 2 | 3 | * [Rust by Example (japaric)](http://rustbyexample.com) - The most complete, and well-presented. 4 | * [Rust Rosetta](https://github.com/Hoverbear/rust-rosetta) - Also fairly complete. 5 | * [The official cheatsheet](http://static.rust-lang.org/doc/master/complement-cheatsheet.html) 6 | * [Getting Rusty](http://pzol.github.io/getting_rusty/) 7 | * [Rust by Example (TheHydroImpulse)](http://rustbyexample.github.io/) 8 | * [Rust for Real](https://github.com/flaper87/rust-for-real) -------------------------------------------------------------------------------- /Libs.md: -------------------------------------------------------------------------------- 1 | List of docs concerning changes to Rust standard libraries 2 | 3 | # Overview docs 4 | 5 | - [[Community libraries]] 6 | - [[How to add or reorganize modules in the Rust standard libraries|Library editing]] 7 | - [[Module editing plan template|Lib template]] 8 | 9 | # Wanted new modules 10 | 11 | - [[DateTime|Lib DateTime]] 12 | - [[Formatting|Lib fmt]] 13 | - [[Html|Lib Html]] 14 | - [[I/O|Lib io]] 15 | - [[SIMD|Lib simd]] 16 | 17 | # Active module edit plans 18 | ## General cross-module cleanup 19 | ## Topical module improvements or additions 20 | 21 | - [[re|Lib re]] 22 | 23 | # Abandoned or completed module edit plans 24 | ## General cross-module cleanup 25 | ## Topical module improvements or additions 26 | 27 | # External candidate Rust packages to adopt -------------------------------------------------------------------------------- /Home.md: -------------------------------------------------------------------------------- 1 | *Hey, listen! Rust is alpha-level software with many known bugs, incomplete features and planned future changes. Use at your own risk, expect some instability, disruption and source-level incompatibility for a while yet.* 2 | 3 | Is this your first time? Then perhaps you would like to [[peruse the docs|Docs]] and [[build the compiler|Note getting started developing Rust]]. 4 | 5 | Want to contribute? [[We love that|Note guide for new contributors]]. 6 | 7 | Rust is developed through an open process by kindly folks who congregate in [#rust on irc.mozilla.org][pound-rust]. If you run into problems, IRC is a good place to ask for help. Please [be nice](https://github.com/mozilla/rust/wiki/Note-development-policy#conduct). 8 | 9 | Please follow some [[conventions|Note wiki conventions]] when editing this wiki. 10 | 11 | [pound-rust]: http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust -------------------------------------------------------------------------------- /Doc-lowlevel-details.md: -------------------------------------------------------------------------------- 1 | ## Method Dispatch 2 | 3 | Type-parameterized functions are specialized for each set of type parameters used to instantiate them in a crate. The method calls are resolved statically at compile-time. Example: 4 | 5 | ```rust 6 | fn foo(x: &T) -> ~str { x.to_str() } 7 | foo(&5u); // `foo` is instantiated for this crate 8 | ``` 9 | Using traits as objects is dynamic dispatch at runtime. The method calls are resolved by dereferencing a pointer to a vtable at runtime and then calling a function pointer. Example: 10 | 11 | ```rust 12 | fn foo(x: &ToStr) -> ~str { x.to_str() } 13 | foo(&5u as &ToStr); // a vtable is generated for `uint` with the `to_str` method 14 | ``` 15 | At runtime, `&ToStr` is represented as a a pointer to a vtable with all the methods in the trait (just `to_str` in this case) and a pointer to the value. The pointer to the value is the pointer sigil in front of the trait object. -------------------------------------------------------------------------------- /Doc continuous integration.md: -------------------------------------------------------------------------------- 1 | Rust is a fast-moving project and it can still be difficult for package maintainers to keep up with the Rust master branch. We recommend that maintainers use [Travis CI](https://travis-ci.com/) to test their packages against Rust nightly builds and register with the [Rust CI](http://hiho.io/rust-ci/) community dashboard. See the Rust CI page for further instructions. 2 | 3 | First things first, you'll need to set up your project with Travis CI. Sign up for an account on their website, and then in Travis's profile page, make sure the project you want to check is enabled. 4 | 5 | Next, you'll need to write a file `.travis.yml` with the single line `language: rust` in the root of your project and you are good to go! All commits and pull requests will launch a new test using `Cargo`. 6 | 7 | See the [full documentation](http://docs.travis-ci.com/user/languages/rust/) on Rust support (for example, if you do not want to run `Cargo` to run tests). -------------------------------------------------------------------------------- /Meeting-RFC-triage-2014-06-19.md: -------------------------------------------------------------------------------- 1 | # RFC triage 2014-06-19 2 | 3 | # Attending 4 | 5 | huon, acrichto, aturon, huon, niko, nrc, luqman, zwarich, brson, cmr 6 | 7 | # Action Items 8 | 9 | - (brson) close https://github.com/rust-lang/rfcs/pull/39 10 | - (brson) close https://github.com/rust-lang/rfcs/pull/76 11 | - (brson) close https://github.com/rust-lang/rfcs/pull/78 12 | 13 | # PR 39 - allocator trait 14 | 15 | - nrc: want to do it, but probably needs new RFC 16 | - brson: why is this not good enough? 17 | - cmr: doesn't reflect current thinking 18 | - niko: tied to GC design. not ready to accept this 19 | 20 | # PR 76 - multiple trait impls for single impl block 21 | 22 | - nrc: recommend postpone 23 | - all: agree 24 | 25 | # PR 78 - extend safe mutability 26 | 27 | - nrc: from mutpocalypse discussion. thought we had agreed to close this previously 28 | - zwarich: brings back aliased mutable data. big change 29 | 30 | # PR 81 - tail call elim 31 | 32 | - cmr: already closed 33 | -------------------------------------------------------------------------------- /IRC-notifications-channel.md: -------------------------------------------------------------------------------- 1 | # IRC notifications 2 | 3 | Notifications (from GitHub, etc.) get posted on the irc channel #rust-bots. 4 | 5 | The following table describes the bots which post to #rust-bots, and who to contact if there are problems: 6 | 7 | | | | | 8 | |---------------|----------------------------------------------------------------|-----------| 9 | | gh-rust | notifications for rust-lang repos, including rust, cargo, rfcs | acrichto | 10 | | gh-rustaceans | notifications from the rustaceans repos | nrc | 11 | | redditbot | posts on r/rust | mcpherrin | 12 | | overflowbot | stackoverflow rust tagged questions | mcpherrin | 13 | | rust-buildbot | buildbot | acrichto | 14 | 15 | If you have any general questions about the channel, ping nrc. 16 | -------------------------------------------------------------------------------- /Sigil-reference.md: -------------------------------------------------------------------------------- 1 | A quick reference of the sigils and their meaning: 2 | 3 | | Sigil | Meaning | 4 | | ----- | ------- | 5 | | `~` | Owned pointer; like a normal value, but always pointer-sized, and allocated on the heap | 6 | | `&` | Borrowed pointer; a pointer to data that you do not own and thus cannot free | 7 | | `&mut`| Mutable borrowed pointer; like a borrowed pointer, but cannot alias with any other pointer, and you can mutate through it | 8 | | `@` | Managed pointer; a pointer to data that no one owns. Allows cycles. Garbage collected | 9 | | `@mut`| Mutable managed pointer; a mutable pointer to data that no one owns. Has runtime checks to make sure it is not mutated at the same time by two different pieces of code, and that when it is borrowed, the guarantees of borrowed pointers are maintained | 10 | | `'` | Lifetime/label marker; used to label loops for labeled break and to indicate the lifetime of a borrowed pointer (eg `&'a T`) | 11 | | `*` | Raw pointer; just like a pointer in C. Requires unsafe code to dereference. Can be NULL | -------------------------------------------------------------------------------- /Doc-building-for-ios.md: -------------------------------------------------------------------------------- 1 | # Rust on iOS 2 | 3 | You need XCode 5. 4 | 5 | Build Rust cross-compiler: 6 | ``` 7 | mkdir build_ios; cd build_ios 8 | ../configure --target=armv7-apple-ios,armv7s-apple-ios,i386-apple-ios,aarch64-apple-ios,x86_64-apple-ios 9 | make 10 | ``` 11 | 12 | Once compilation complete you can use it. 13 | 14 | To target device (depending on dest architecture): 15 | ``` 16 | rustc --target=armv7-apple-ios foo.rs 17 | ``` 18 | 19 | ``` 20 | rustc --target=armv7s-apple-ios foo.rs 21 | ``` 22 | 23 | ``` 24 | rustc --target=aarch64-apple-ios foo.rs 25 | ``` 26 | 27 | To target simulator: 28 | ``` 29 | rustc --target=i386-apple-ios foo.rs 30 | ``` 31 | 32 | ``` 33 | rustc --target=x86_64-apple-ios foo.rs 34 | ``` 35 | 36 | ## What you get 37 | 38 | * all Rust superpowers 39 | * exception handling 40 | * LLDB debugging 41 | 42 | ## Known limitations 43 | 44 | * segmented stack is disabled that means no stack protection available 45 | 46 | ## Resources 47 | 48 | * [Sample](https://github.com/vhbit/ObjCrust) of using Rust from Objective C + Makefile for simultaneous compiling for both device and simulator (all architectures) -------------------------------------------------------------------------------- /Note-wiki-conventions.md: -------------------------------------------------------------------------------- 1 | The GitHub Wiki system is generally good but suffers from a few missing built-in features: 2 | 3 | * Categorization 4 | * Tagging 5 | * Namespacing 6 | 7 | This makes it tricky to navigate. On the upside, it's written in simple Markdown and can be accessed [through git](_access). This makes it very easy to keep manually organized, in the local filesystem. 8 | 9 | A couple important points to keep in mind when editing and, particularly, naming pages: 10 | 11 | * Please use Markdown, not one of the many other markup languages GitHub provides. 12 | * Let the filename be the title. Do not put any initial headers in pages, as GitHub will (in some places) use that as the title rather than the filename. The filename is what you make internal wiki-links to (with dashes turned into spaces). Just use that name. 13 | * We _manually maintain_ a category list in the file `_Sidebar.md`, which turns into the sidebar on all pages. 14 | * Prefix every non-navigation page name with a category name. Crude, but it works. So when you make a developer note about foo, call it `Note-foo.md`. If it makes you uncomfortable, squint a bit and imagine the category name as a directory name. 15 | -------------------------------------------------------------------------------- /Note-rustc-hacking-guide---front-end.md: -------------------------------------------------------------------------------- 1 | The compiler front-end includes the lexer, parser and syntax extensions (macros), among other things. The front-end is in a separate crate, called ```syntax```, whose source files live in the ```src/libsyntax``` directory under the main Rust source tree. (The middle and back end are in ```src/librustc```.) 2 | 3 | ## Syntax extensions 4 | Built-in syntax extensions are located in ```src/libsyntax/ext```, including the macro-defining construct ```macro```, located in ```simplext.rs```. It also contains ```expand.rs```, which is responsible for traversing and expanding the tree in the first place, and ```base.rs```, which contains helper functions for extensions and registers the extensions for the expander. 5 | 6 | ## Parser 7 | Rust's parser, located in ```src/libsyntax/parse/parser.rs``` is a hand-rolled LL-style parser with a small, finite lookahead. Rust's lexer is in ```src/libsyntax/parse/lexer.rs```. 8 | 9 | ## Adding a new keyword 10 | 11 | If you need to add a new keyword to Rust (a rare occurrence, with hope!) edit one or the other of the functions ```reserved_keyword_table``` or ```strict_keyword_table``` in ```src/libsyntax/parse/token.rs```. Together, these functions construct the table that parser functions consult when determining which identifiers are keywords. -------------------------------------------------------------------------------- /Note-Intrinsics.md: -------------------------------------------------------------------------------- 1 | Intrinsics are implemented in Rust as special functions that directly generate LLVM IR in their bodies. This allows for very specific code to be generated which is useful when implementing very low level features. 2 | 3 | However, adding new intrinsics can be tricky. There are 3 places that you need to alter in order to add an intrinsic: `typeck/check/mod.rs`, `trans/foreign.rs` and `trans/type_use.rs`. All three places need to be updated in order for the intrinsic to be available. In order to use the intrinsic in code, you then need to declare it with the correct signature and the abi "rust-intrinsic". 4 | 5 | ### In Typeck 6 | 7 | In `typeck/check/mod.rs` there is a function called `check_intrinsic_type`, inside there is a match statement that matches against the name of the intrinsic. Look at the other examples to get an idea of what you need to enter here. This is where the type checker checks your function declaration in the source, so you need to make sure they match. This is because intrinsics are often declared where ever they are needed, so the types all need to match 8 | 9 | ### In Foreign 10 | 11 | This is where rust translates the foreign declaration into LLVM code. Here you can again look at the surrounding code to get an idea of what to enter. 12 | 13 | ### In Type Use 14 | 15 | This is where rust determines if it can combine function bodies for generic functions. This means you need an entry for your intrinsic, so rust knows it exists. -------------------------------------------------------------------------------- /Note-core-team.md: -------------------------------------------------------------------------------- 1 | Rust has a community-driven development process where most decisions are made through consensus, under the stewardship of a 'core team'. The core team is responsible for steering the design and development process, overseeing the introduction of new features, and ultimately making decisions for which there is no consensus (this happens rarely). 2 | 3 | | Name | IRC | GitHub | email | 4 | |:-------------------|:-------------|:------------------|:-----------------------| 5 | | Aaron Turon | aturon | [aturon][1] | aturon@mozilla.com | 6 | | Alex Crichton | acrichto | [alexcrichton][2] | acrichton@mozilla.com | 7 | | Brian Anderson | brson | [brson][3] | banderson@mozilla.com | 8 | | Huon Wilson | huon | [huonw][4] | dbau.pp@gmail.com | 9 | | Niko Matsakis | nmatsakis | [nikomatsakis][5] | nmatsakis@mozilla.com | 10 | | Patrick Walton | pcwalton | [pcwalton][6] | pcwalton@mozilla.com | 11 | | Yehuda Katz | wycats | [wycats][7] | wycats@gmail.com | 12 | | Steve Klabnik | steveklabnik | [steveklabnik][8] | steve@steveklabnik.com | 13 | 14 | [1]: https://github.com/aturon 15 | [2]: https://github.com/alexcrichton 16 | [3]: https://github.com/brson 17 | [4]: https://github.com/huonw 18 | [5]: https://github.com/nikomatsakis 19 | [6]: https://github.com/pcwalton 20 | [7]: https://github.com/wycats 21 | [8]: https://github.com/steveklabnik 22 | -------------------------------------------------------------------------------- /Community-User-Groups,-Meetups,-and-Events.md: -------------------------------------------------------------------------------- 1 | Rust has a large and growing international community. There are a number of local user groups, meetups, and events spread around the world that are friendly to people with all skill levels. Check the [Community Calendar](https://www.google.com/calendar/embed?src=apd9vmbc22egenmtu5l6c5jbfc%40group.calendar.google.com) for upcoming events. 2 | 3 | International: 4 | - [Air Mozilla - Rust](https://air.mozilla.org/?tag=rust): Live and archived presentations from a variety of meetups. 5 | 6 | Paris, France: 7 | - [Rust Paris](http://www.meetup.com/Rust-Paris/) 8 | 9 | Berlin, Germany: 10 | - [Rust Berlin](http://www.meetup.com/Rust-Berlin/) 11 | 12 | Skåne, Sweden: 13 | - [Rust Skåne](http://www.meetup.com/rust-skane/) 14 | 15 | London, UK: 16 | - [Rust London User Group](http://www.meetup.com/Rust-London-User-Group/) 17 | 18 | Geneva, Switzerland: 19 | - [Rust Romandie](http://www.meetup.com/rust-romandie/) 20 | 21 | Brooklyn, NY, USA: 22 | - [Brooklyn.rs](http://brooklyn.rs/) 23 | 24 | Columbus, OH, USA: 25 | - [Columbus Rust Society](http://www.meetup.com/columbus-rs/) 26 | 27 | Pittsburgh, PA, USA: 28 | - [Pittsburgh Code Supply](http://www.meetup.com/Pittsburgh-Code-Supply/) 29 | 30 | Portland, OR, USA: 31 | - [PDX-Rust](https://groups.google.com/forum/?#!forum/pdx-rust) 32 | 33 | San Francisco, CA, USA: 34 | - [Rust Bay Area](http://www.meetup.com/Rust-Bay-Area/): Monthly meetups that range from tutorials for new users to the innards of Rust and the Rust community libraries. Live streamed on [Air Mozilla](https://air.mozilla.org). 35 | - [Rust Hacknights](http://www.meetup.com/SF-Rust-Hacknights/) -------------------------------------------------------------------------------- /lib-template.md: -------------------------------------------------------------------------------- 1 | Module editing plan template 2 | 3 | ## 1. Announcement to mailing list 4 | 5 | - Proposed editor: _your name_ 6 | - Date proposed: _date of proposal_ 7 | - Link: _link to email_ 8 | 9 | ### Notes from discussion on mailing list 10 | 11 | - _note_ 12 | - _note_ 13 | - _note_ 14 | 15 | ## 2. Research of standards and techniques 16 | 17 | 1. Standard: _standard_ 18 | - _link to docs_ 19 | - ... 20 | 2. Standard: _standard_ 21 | - _link to docs_ 22 | - ... 23 | 1. Technique: _technique_ 24 | - _link to docs_ 25 | - ... 26 | 2. Technique: _technique_ 27 | - _link to docs_ 28 | - ... 29 | 30 | ### Summary of research on standards and leading techniques 31 | #### Relevant standards and techniques exist? 32 | #### Those intended to follow (and why) 33 | #### Those intended to ignore (and why) 34 | 35 | ## 3. Research of libraries from other languages 36 | 37 | 1. Language: _language_ 38 | - _link to library_ 39 | - ... 40 | 2. Language: _language_ 41 | - _link to library_ 42 | - ... 43 | 3. Language: _language_ 44 | - _link to library_ 45 | - ... 46 | 4. Language: _language_ 47 | - _link to library_ 48 | - ... 49 | 50 | ### Summary of research from other languages: 51 | #### Structures and functions commonly appearing 52 | #### Variations on implementation seen 53 | #### Pitfalls and hazards associated with each variant 54 | #### Relationship to other libraries and/or abstract interfaces 55 | 56 | ## 4. Module writing 57 | 58 | - Pull request: _link to bug_ 59 | 60 | ### Additional implementation notes 61 | 62 | - _note_ 63 | - _note_ 64 | - _note_ -------------------------------------------------------------------------------- /Note-code-review.md: -------------------------------------------------------------------------------- 1 | Code review checklist 2 | --------------------- 3 | 4 | * Code should respect the policy described in the [style](https://github.com/mozilla/rust/wiki/Note-style-guide) page. 5 | * Commit message summaries have to be descriptive. 6 | * Commit messages should be *accurate*: if it has deviated from top-level description, don't `r+` without getting that fixed; see e.g. [flip-i-mean-rev commit](../commit/bf9c25562da1c0e768309693617e54e998a953d1) as an example of accidental deviation. 7 | * Almost every change should contain a test case as described in the [testing](https://github.com/mozilla/rust/wiki/Doc-unit-testing) page. 8 | * Code optimization should contain a bench case as described in the [bench](https://github.com/rust-lang/rust/wiki/Note-testsuite#benchmarks-saved-metrics-and-ratchets) section of the [testing](https://github.com/rust-lang/rust/wiki/Note-testsuite) page. 9 | * Look for commits that could be squashed. 10 | 11 | General Suggestions 12 | ------------------- 13 | 14 | * Don't do partial reviews. If you're reviewing a PR, address it completely. This will reduce the pending time of PRs. 15 | * Whenever something can be improved or should be changed, be as detailed as possible in your comments. This will help contributors that are not familiar with the code to understand better what you're saying. 16 | * Add references whenever it's possible. For instance, when a benchmark is requested, link the benchmark section to your comment, unless you're sure the contributor knows that already. 17 | 18 | Non core contributors 19 | --------------------- 20 | 21 | * If you reviewed a patch and code looks good to you, use `LGTM` instead of `r+` 22 | -------------------------------------------------------------------------------- /Note-operator-overloading.md: -------------------------------------------------------------------------------- 1 | --- 2 | **Moved into [the standard library documentation for `std::ops`](http://doc.rust-lang.org/master/std/ops/).** 3 | 4 | --- 5 | 6 | We currently (May 2013) have a simple form of operator overloading. There are a few traits (in `std::ops`), that provide methods that are called for each operator, e.g. 7 | 8 | ```rust 9 | struct Point {x: int, y: int}; 10 | 11 | impl Add for Point { 12 | fn add(&self, other: &Point) -> Point { 13 | Point {x: self.x + other.x, y: self.y + other.y} 14 | } 15 | } 16 | 17 | impl Sub for Point { 18 | fn sub(&self, other: &Point) -> Point { 19 | Point {x: self.x - other.x, y: self.y - other.y} 20 | } 21 | } 22 | fn main() { 23 | Point {x: 1, y: 0} + Point {x: 2, y: 3} 24 | } 25 | ``` 26 | 27 | When this impl is in scope, and binary + or - are applied to two values of type `Point`, the operators will turn into calls to these methods. Operator/type combinations that are defined 'natively' by the language can not be overloaded (for example + on int). The generics on the trait correspond to the right hand side and the result of the operation, which are not required to be the same as the left hand side (the type the trait is being implemented for). 28 | 29 | The operators that can be overloaded are: `+`, `-` (both unary and binary), `*`, `/`, `%`, `&`, `|`, `^`, `<<`, `>>`, `!` (unary) and `[]` (the index operator). The names of the methods and traits used to implement them correspond to the names in English (the traits are `Add`, `Sub`, `Neg`, `Mul`, `Div`, `Rem`, `BitAnd`, `BitOr`, `BitXor`, `Shr`, `Shl`, `Not` and `Index` and the methods are just the trait name in lowercase). 30 | 31 | The values for an operator are automatically borrowed, so `a + b` is sugar for `(&a).add(&b)`. -------------------------------------------------------------------------------- /Notes.md: -------------------------------------------------------------------------------- 1 | Listing of notes for developers working on the Rust compiler and tools. 2 | The developer forum is located at http://discuss.rust-lang.org/. 3 | 4 | ## Process and workflow notes 5 | 6 | * [[Note guide for new contributors]] 7 | * [[Note getting started developing Rust]] -- How to **Build Rust** on your platform 8 | * [[Note development policy]] -- **please read this** 9 | * [Note RFC process](https://github.com/rust-lang/rfcs/blob/master/text/0002-rfc-process.md) -- **read this for larger changes** 10 | * [[Note priority issue criteria]] -- criteria used for evaluating high priority issues 11 | * [[Note wiki conventions]] 12 | * [[Note compiler snapshots]] 13 | * [[Note git workflow]] 14 | * [[Note tag label names and definitions]] 15 | * [Note style guide](https://github.com/rust-lang/rust-guidelines) 16 | * [[Note bors usage]] - Instructing bors to build, check, and merge on github 17 | * [[IRC notifications channel]] 18 | * [[Note testsuite]] - How Rust's tests are organized and operated 19 | * [[Note rustc hacking guide]] 20 | * [[Note code review]] 21 | 22 | ## Miscellaneous notes 23 | 24 | * [[Note seeing LLVM output from rust]] 25 | * [[Note research]] - Links to research that influenced Rust. 26 | 27 | ## Tools 28 | 29 | * [Bors's Queue](http://buildbot.rust-lang.org/homu/queue/rust) - Our [integration bot, bors](https://github.com/bors) tries to keep the build green. 30 | * [buildbot](http://buildbot.rust-lang.org) - All pull requests go through buildbot, via bors. 31 | * [isrustfastyet](http://huonw.github.io/isrustfastyet/mem/) 32 | * [IRC quotes](http://quotes.burntelectrons.org/search?query=tag%3A%23rust) 33 | * [IRC logs](https://botbot.me/mozilla/rust) and [more IRC logs](http://irclog.gr/#browse/irc.mozilla.org/rust) 34 | * [MXR](http://mxr.mozilla.org/rust/) 35 | * [PR Triage](https://prs.paas.allizom.org/mozilla/rust) -------------------------------------------------------------------------------- /Projects-using-Rust.md: -------------------------------------------------------------------------------- 1 | Mozilla projects 2 | ---------------- 3 | 4 | * The Rust compiler 5 | * [servo](https://github.com/mozilla/servo): A browser engine 6 | 7 | Applications 8 | ------------ 9 | 10 | * [q3](https://github.com/Jeaye/q3): Quake-like game (stylized "Q^3") 11 | * [rustboot](https://github.com/charliesome/rustboot): A tiny 32-bit kernel 12 | * [rustray](https://github.com/brson/rustray): A raytracer 13 | * [rust-airhockey](https://github.com/FrozenCow/rust-airhockey): An air hockey game 14 | * [shorai](https://github.com/jmgrosen/shorai): A super-amazing OS that will bring world peace. 15 | * [sprocketnes](https://github.com/pcwalton/sprocketnes): An NES emulator 16 | * [crust](https://github.com/mkandalf/crust): A chess engine 17 | 18 | Libraries 19 | --------- 20 | 21 | * [cgmath](https://github.com/bjz/cgmath-rs): A linear algebra library 22 | * [sharegl](https://github.com/mozilla-servo/sharegl): An OpenGL context library 23 | 24 | Bindings 25 | -------- 26 | 27 | * [rust-azure](https://github.com/servo/rust-azure): Bindings to mozilla-central's graphics abstraction layer 28 | * [glfw-rs](https://github.com/bjz/glfw-rs/): GLFW3 bindings and idiomatic wrapper 29 | * [rust-curses](https://github.com/kballard/rust-curses): Interface to terminal ncurses library / libraries 30 | * [rust-openssl](https://github.com/sfackler/rust-openssl): OpenSSL bindings 31 | * [rust-sdl](https://github.com/brson/rust-sdl): SDL bindings 32 | * [rust-sfml](https://github.com/JeremyLetang/rust-sfml): SFML bindings 33 | * [rustsqlite](https://github.com/linuxfood/rustsqlite): Sqlite3 bindings 34 | 35 | Competitions 36 | ------------ 37 | 38 | * At least one finishing entry for the Matasano security challenges 39 | * Two ICFP programming contest entries (using v0.3): [Emarhavil Heavy Industries](https://github.com/emarhavilicfp/icfp) and [Celestial Dire Badger](https://github.com/jld/icfpc12) -------------------------------------------------------------------------------- /Mixed-language-link-time-optimization.md: -------------------------------------------------------------------------------- 1 | This can be done with or without the runtime enabled, but the example here will disable it in order to demonstrate a very simple optimization enabled by LTO. 2 | 3 | main.c 4 | 5 | ```c 6 | #include 7 | #include 8 | 9 | uint32_t *foo(); 10 | 11 | int main(void) { 12 | free(foo()); 13 | return 0; 14 | } 15 | ``` 16 | 17 | foo.rs 18 | 19 | ```rust 20 | #[no_std]; 21 | #[allow(ctypes)]; 22 | 23 | extern { 24 | fn malloc(size: uint) -> *mut u8; 25 | fn free(ptr: *mut u8); 26 | fn abort() -> !; 27 | } 28 | 29 | #[lang = "exchange_malloc"] 30 | unsafe fn exchange_malloc(size: uint) -> *mut u8 { 31 | let ptr = malloc(size); 32 | if ptr == 0 as *mut u8 { 33 | abort() 34 | } 35 | ptr 36 | } 37 | 38 | #[lang = "exchange_free"] 39 | unsafe fn exchange_free(ptr: *mut u8) { 40 | free(ptr) 41 | } 42 | 43 | #[no_mangle] 44 | extern "C" fn foo() -> ~u32 { ~5 } 45 | ``` 46 | 47 | Build LLVM bytecode from the Rust code: 48 | 49 | $ rustc foo.rs --emit-llvm --lib -O 50 | 51 | The `--lib` flag is necessary even if Rust defines `main`, to avoid treating 52 | the Rust part as the entire application. 53 | 54 | Compile together the C and Rust code with `clang`: 55 | 56 | $ clang foo.bc main.c -flto -O3 -o main 57 | 58 | Verify that LLVM eliminated the call to `foo` via inlining and removed the 59 | allocation as a dead store: 60 | 61 | $ gdb main 62 | (gdb) disassemble main 63 | Dump of assembler code for function main: 64 | 0x00000000004005b0 <+0>: xor %eax,%eax 65 | 0x00000000004005b2 <+2>: retq 66 | End of assembler dump. 67 | 68 | To do this with the Rust runtime on, define a regular `main` function in Rust and pass the necessary link flags to `clang`. The necessary switches can be obtained with `rustc -Z print-link-args foo.rs`. In order for segmented stacks to work, `rustc` will likely need to be taught to take LLVM bytecode files as input to combine with the current crate. -------------------------------------------------------------------------------- /Using-Rust-on-Windows.md: -------------------------------------------------------------------------------- 1 | As of release 0.12, Rust distribution for Windows is completely self-contained and includes all dependencies from MinGW toolchain required for building Windows binaries. 2 | 3 | Notes: 4 | 5 | 1. Rust compiler uses `gcc` as a linker driver, and will search for it in the system `PATH` before searching in the private directory. This means that any other versions found on `PATH` will override the one bundled with Rust, and may cause linking errors if they aren't compatible. The solution is to strip down the `PATH` in the console session used to launch `rustc`. 6 | 2. The 32-bit binaries produced by `rustc` will depend on the shared GCC runtime library, `libgcc_s_dw2-1.dll`, which you will need to distribute along with your program. You'll find it in the `/bin` directory. 7 | The 64-bit binaries are dependency-free. 8 | 9 | ## Using Rust with MSYS2 10 | If you want to use any dependencies that depend on C/C++ bits you will likely need a separately installed mingw as the mingw bundled with Rust is not capable of compiling C/C++ code, and only includes a minimal set of libs for system libraries. The recommended way to do this is using MSYS2. 11 | 12 | 1. Download and install MSYS2 from http://msys2.github.io/. 13 | 2. Download and install Rust+Cargo using the installer but be sure to disable the `Linker and platform libraries` option. 14 | 3. Ensure that Rust is in your `PATH` and that there are no mingw installations in your `PATH`. 15 | 4. Launch your MSYS2 environment using either `mingw32_shell.bat` or `mingw64_shell.bat` depending upon which version of Rust you installed. 16 | 5. Install the mingw toolchain using `pacman -S mingw-w64-x86_64-toolchain` or `pacman -S mingw-w64-i686-toolchain` depending upon which version of Rust you installed. 17 | 6. Install the base set of developer tools using `pacman -S base-devel`. 18 | 19 | 20 | *These instructions cover running Rust from a binary installation. To build Rust see [[further instructions|Note-getting-started-developing-Rust]].* -------------------------------------------------------------------------------- /Teaching-Rust.md: -------------------------------------------------------------------------------- 1 | Firstly, we've lately been thinking about how to introduce Rust to 2 | experienced programmers and these are the topics, in roughly this order, 3 | that we believe are critical to teach: 4 | 5 | - Stack vs. heap, values, copying 6 | - Ownership (front and center) 7 | - Borrowing 8 | - Copying vs. Moving (and the notion of Pods for copying) 9 | - References vs. values, and their relationship to ownership and 10 | stack/heap allocation 11 | - Lifetimes (specifically taught in terms of returning borrowed fields 12 | of a struct) 13 | 14 | It's impossible to understand Rust without grasping these concepts, and 15 | the earlier and more frequently they are taught the better. 16 | 17 | Then there are a number of practical subjects that all Rust programmers 18 | need to know to write real code: 19 | 20 | - Vectors vs. Slices 21 | - Structs, enums, and pattern matching 22 | - Also covered in passing, with links to guides for further info: fns, 23 | impls, basic types, using libraries, `Option`, generics 24 | 25 | For an example of how to teach Rust I recommend watching [Niko's recent 26 | talk](http://mirror.linux.org.au/pub/linux.conf.au/2014/Friday/107-The_Rust_language_memory_ownership_and_lifetimes_-_Nicholas_Matsakis.mp4) 27 | 28 | # Rust relating to other languages 29 | 30 | One good resource is Rust for [C++ programmers]. 31 | 32 | I consider Rust to be a multi-paradigm systems language, not 33 | specifically functional, not specifically OO, but drawing influence from 34 | both. The biggest influences are probably C++ and ML. It's design is 35 | influenced by existing languages, but more importantly by practical 36 | experience solving problems of memory safety, performance, and 37 | concurrency in large-scale software ([Servo]). To that end it deviates 38 | from precedent established in other mainstream programming languages, 39 | introducing the key concepts of ownership and borrowing. 40 | 41 | [C++ programmers]: https://github.com/mozilla/rust/wiki/Rust-for-CXX-programmers 42 | [Servo]: https://github.com/servo/servo -------------------------------------------------------------------------------- /Note-Rust-performance-fixes.md: -------------------------------------------------------------------------------- 1 | This is a page of random performance ideas, mostly from pcwalton. 2 | 3 | pcwalton: 4 | graydon: there are a bunch of unnecessary allocations in trans 5 | 6 | pcwalton: 7 | I fixed a bunch of 'em but there are certainly more 8 | 9 | pcwalton: 10 | one thing that would very much help is a SmallVector in libstd 11 | 12 | pcwalton: 13 | fail() really needs to be a lang_item and it needs to be parameterized over ToStr 14 | 15 | pcwalton: 16 | the idea being that if you're failing with a constant string 17 | 18 | pcwalton: 19 | it should not call upcall_new_str_uniq() at the site of failure 20 | 21 | pcwalton: 22 | rather it should pass a string slice (&static/str) to a function which itself copies the string 23 | 24 | pcwalton: 25 | move the copy out of line 26 | 27 | pcwalton: 28 | likewise fmt! generates a ton of code. most of the time the unique string it produces is not really being used, except to be written once and thrown away 29 | 30 | graydon: 31 | mhm 32 | 33 | pcwalton: 34 | (1) stop zeroing stuff out to revoke cleanups, use a flag instead to indicate whether the dtor needs to be run (this is potentially a quite large win) 35 | 36 | pcwalton: 37 | (2) try to coalesce failure landing pads instead of duplicating the cleanups all the time 38 | 39 | pcwalton: 40 | also ty::sty comparison in the ty hashtable is calling into the shape glue. I'm going to try to fix that this week 41 | 42 | pcwalton: 43 | oh yeah, another thing I was thinking: stop making so many basic blocks 44 | 45 | pcwalton: 46 | especially when optimization is off, LLVM goes basic-block-by-basic-block in codegen 47 | 48 | pcwalton: oh yeah, we should also see if we can get away with not zeroing out memory when we allocate it 49 | 50 | pcwalton: 51 | that's like 5% of our performance right there 52 | 53 | pcwalton: 54 | in some profiles anyway 55 | 56 | ## Memory moves 57 | 58 | If you see large sequences of "mov" instructions, use `call_memmove` or `memzero` in trans, as appropriate. This is usually a symptom of code like `Store(bcx, Load(bcx, foo, bar), baz);`, which is *not* an efficient way to move large structural types around. -------------------------------------------------------------------------------- /Note-bors-usage.md: -------------------------------------------------------------------------------- 1 | There is an auto-merge robot running on rust-lang/rust; its name is "bors"; 2 | it has a github account and is listed as a collaborator in the `rust-push` group. 3 | Its source is available [on GitHub](https://github.com/graydon/bors). 4 | 5 | Its status URL is: http://buildbot.rust-lang.org/homu/queue/rust 6 | 7 | It works by scanning pull requests for r+ _on the commit_ (*not* the pull request) 8 | from one of the reviewers. It also accepts the following input: 9 | 10 | * `r=name[,name...]` to specify that the given person(s) should be marked as the reviewer(s), rather than whoever left the comment 11 | * `p=number` to specify the priority that the PR should be tested. Higher priority is tested first. Ties are resolved by date the PR was opened. 12 | 13 | For the most part no knowledge of bors is required of people submitting pull 14 | requests. When a reviewer signs off on one of your commits by writing "r+" 15 | in a comment on the final commit of a pull request, bors will automatically: 16 | 17 | - Reset the `auto` branch to `master` 18 | - Attempt to merge your pull request into `auto` --- if this fails, your request will be marked as stale, meaning you will need to rebase it. 19 | - Wait for buildbot to test `auto` 20 | - If successful, fast-forward `master` to `auto` 21 | - Otherwise report how the change failed 22 | 23 | Rebased pull requests require re-approval. 24 | 25 | There is a certain degree of chatter from bors as it steps through its automation. 26 | It makes comments, such as in this pull request: 27 | 28 | https://github.com/mozilla/rust/pull/4832 29 | 30 | It retries if you move incoming while it's working, so tends to behave 31 | "mostly gracefully" with respect to disruption around it. If it 32 | misbehaves, it can be provoked to retry a commit with a comment from a 33 | reviewer saying "@bors: retry" (on that same commit as the original "r+", as 34 | opposed to the comment-trail inlined the Pull Request itself). 35 | It ignores comments by non-reviewers. It 36 | also does not merge "updates" to a pull request. It considers comments on 37 | commits only, not pull requests; if you update a pull request to contain new 38 | commits, they need to be reviewed anew. -------------------------------------------------------------------------------- /Note-seeing-LLVM-output-from-rust.md: -------------------------------------------------------------------------------- 1 | ## General purpose 2 | 3 | In your build directory, invoke the Rust compiler with the `--emit=llvm-ir` flag. It will look something like: 4 | 5 | ``` 6 | rustc --emit=llvm-ir hello.rs 7 | ``` 8 | 9 | An LLVM IR file that you can read will now be sitting in `hello.ll`. 10 | 11 | ``` 12 | less hello.ll 13 | ``` 14 | 15 | -------- 16 | 17 | ### I want to check the test result of the Rust compiler 18 | 19 | Recall that if the test you want to run is in `test/run-pass/hello.rs`, the invocation (as described in [[Note-testsuite]] page) is 20 | 21 | ``` 22 | make check TESTNAME=test/run-pass/hello.rs 23 | ``` 24 | 25 | If you stick a `VERBOSE=1` in front of that, you'll see what's happening under the hood. So, for instance: 26 | 27 | ``` 28 | VERBOSE=1 make check TESTNAME=test/run-pass/hello.rs 29 | ``` 30 | 31 | will spit out a bunch of verbose output, including (if you scroll up a ways) various calls to `compiletest`, the test runner, one of which will look something like: 32 | 33 | ``` 34 | stage2/bin/compiletest --compile-lib-path stage2/lib --run-lib-path stage2/lib/rustc/i686-unknown-linux-gnu/lib --rustc-path stage2/bin/rustc --stage-id stage2 --rustcflags "-O" test/run-pass/hello.rs --verbose --src-base ../rust/src/test/run-pass/ --build-base test/run-pass/ --mode run-pass --runtool "/usr/bin/valgrind --leak-check=full --error-exitcode=100 --quiet --suppressions=../rust/src/etc/x86.supp" 35 | ``` 36 | 37 | You can manually add the `-C -save-temps` flag to the `--rustcflags` list, and the test runner will pass it along to the compiler. So the entire invocation, for this particular test, becomes: 38 | 39 | ``` 40 | stage2/bin/compiletest --compile-lib-path stage2/lib --run-lib-path stage2/lib/rustc/i686-unknown-linux-gnu/lib --rustc-path stage2/bin/rustc --stage-id stage2 --rustcflags "-O -C -save-temps" test/run-pass/hello.rs --verbose --src-base ../rust/src/test/run-pass/ --build-base test/run-pass/ --mode run-pass --runtool "/usr/bin/valgrind --leak-check=full --error-exitcode=100 --quiet --suppressions=../rust/src/etc/x86.supp" 41 | ``` 42 | 43 | After doing that, your LLVM bitcode file will be sitting in `test/run-pass/hello.bc` and you can disassemble it with `llvm-dis` (which may be found in, e.g., `rust/llvm/x86_64-unknown-linux-gnu/Release+Asserts/bin/`). 44 | -------------------------------------------------------------------------------- /Operating-system-development.md: -------------------------------------------------------------------------------- 1 | This page aims at referencing here resources and documentation about operating system development with Rust. 2 | 3 | ### Community 4 | 5 | * [#rust-osdev on irc.mozilla.org](http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-osdev) 6 | 7 | ### Projects 8 | 9 | Here is a short list of some OS projects in Rust. Feel free to add your own: 10 | 11 | * [ryanra/RustOS](https://github.com/ryanra/RustOS) 12 | * [LeoTestard/Quasar](https://github.com/LeoTestard/Quasar.git) 13 | * [pcmattman/rustic](https://github.com/pcmattman/rustic.git) 14 | * [pczarn/rustboot](https://github.com/pczarn/rustboot.git) 15 | * [wbthomason/ironkernel](https://github.com/wbthomason/ironkernel), a fork of rustboot. 16 | * [thiagopnts/rustico](https://github.com/thiagopnts/rustico), yet another tiny 32 bits kernel 17 | * [Arcterus/kRnel](https://github.com/Arcterus/kRnel.git) 18 | * [cmr/cmoss](https://github.com/cmr/cmoss), a rather inactive OS project 19 | * [mahrz/rv6](https://github.com/mahrz/rv6.git), a port of xv6 an educational unix clone by MIT (doesn't do much yet, currently inactive) 20 | * [eholk/Boot2Rust](https://github.com/eholk/Boot2Rust) - A UEFI application written in Rust. 21 | * [uutils/coreutils] (https://github.com/uutils/coreutils) - coreutils written in Rust. 22 | * [vertexclique/trafo] (https://github.com/vertexclique/trafo) - util-linux written in Rust. 23 | * [hackndev/zinc] (https://github.com/hackndev/zinc) - bare metal stack for ARM, currently targeting LPC1768 K20, Tiva, and STM32F4. 24 | * [mvdnes/element76](https://github.com/mvdnes/element76) - A small i686 kernel 25 | * [thepowersgang/rust_os](https://github.com/thepowersgang/rust_os) - A very minimal (and incomplete) x86_64 kernel 26 | * [thepowersgang/rust-barebones-kernel](https://github.com/thepowersgang/rust-barebones-kernel) - An x86_64/x86 barebones kernel, ready for extending (Public Domain) 27 | * [ckkashyap/rustix] (https://github.com/ckkashyap/rustix/wiki) - Port of xv6 (64bit) to Rust 28 | * [nopaniers/Ming](https://github.com/nopaniers/ming) - Displays a splash screen on Android emulator, more to come. 29 | 30 | ### Resources and docs 31 | 32 | Contents to come.. 33 | 34 | * [The OS-dev wiki](http://wiki.osdev.org/) 35 | * [ARM Infocenter](http://infocenter.arm.com/help/index.jsp) 36 | * [X86 Opcode and Instruction Reference](http://ref.x86asm.net/) 37 | * [Context Switching on X86](http://samwho.co.uk/blog/2013/06/01/context-switching-on-x86/) 38 | * [Rust's __morestack implementation](https://github.com/mozilla/rust/blob/master/src/rt/arch/i386/morestack.S) -------------------------------------------------------------------------------- /Doc-Emacs-Support.md: -------------------------------------------------------------------------------- 1 | ## On-the-fly Syntax Checking 2 | Install `flycheck` from the Package Manager. 3 | 4 | Use `flycheck-mode` in your Rust buffer and it will highlight syntax errors on the fly. It uses the default `rustc` on your machine. 5 | 6 | To make it use a particular rustc binary, you have to create your own syntax-checker. Like this one, for Servo. 7 | ``` lisp 8 | (flycheck-define-checker servo-rust 9 | "A Rust syntax checker using the Rust compiler in Servo." 10 | :command ("/path/to/servo/rustc" 11 | "--parse-only" 12 | source) 13 | :error-patterns 14 | ((error line-start (file-name) ":" line ":" column ": " 15 | (one-or-more digit) ":" (one-or-more digit) " error: " 16 | (message) line-end)) 17 | :modes rust-mode) 18 | 19 | (add-hook 'rust-mode-hook (lambda () (flycheck-select-checker 'servo-rust))) 20 | 21 | ``` 22 | 23 | ## Simple Auto-Completion 24 | For basic auto-completion of symbols available in open buffers, use `M-/` (`dabbrev-expand`) 25 | 26 | ## Auto-Complete mode 27 | This lets you view the potential completions in a pop-up right after point. You can choose among the candidates using `M-n / M-p` 28 | 29 | ## Imenu: Finding definitions within a file 30 | Use `M-x imenu` to choose from a list of all the items in a file (e.g., functions, structs, traits, etc.). 31 | 32 | ### Idomenu 33 | Install the package `idomenu` from the Package Manager. 34 | 35 | Now `M-x idomenu` will let you choose from the items in a file, using Ido completion (fuzzy completion). 36 | 37 | ## Tags 38 | 39 | ### To create the Tags table for Emacs 40 | Assuming RUST_ROOT is where the Rust source is, and PROJECT_DIR is your project 41 | ``` bash 42 | RUST_ROOT=~/rust 43 | RUST_OPTIONS_FILE=$RUST_ROOT/src/compiler/rust/src/etc/ctags.rust 44 | PROJECT_DIR=~/project 45 | ctags-exuberant -e -f TAGS.emacs --languages=rust --options=$RUST_OPTIONS_FILE -R $PROJECT_DIR 46 | ``` 47 | will build the tags table in TAGS.emacs (may take a couple of seconds if it is a big project like Servo or Rust itself). 48 | 49 | Note that this only creates tags for Rust files (`--languages=rust`). Otherwise, there are too many name clashes with random structs in C or C++ files. 50 | 51 | You can then jump to the definition of any function or struct or enum by using `M-.` (`Alt + .`) 52 | 53 | ## Moving around the buffer 54 | Emacs motions like `C-M-a` and `C-M-e` (`beginning-of-defun` and `end-of-defun`) work out of the box. 55 | 56 | So does `C-M-h` (`mark-defun`). 57 | 58 | You can use them to manipulate Rust items - functions, structs, enums, etc. 59 | -------------------------------------------------------------------------------- /Lib-html.md: -------------------------------------------------------------------------------- 1 | A library/module for escaping/unescaping of special HTML characters. 2 | 3 | ## 1. Announcement to mailing list 4 | 5 | - Proposed editor: _your name_ 6 | - Date proposed: _date of proposal_ 7 | - Link: _link to email_ 8 | 9 | ### Notes from discussion on mailing list 10 | 11 | - _note_ 12 | - _note_ 13 | - _note_ 14 | 15 | ## 2. Research of standards and techniques 16 | 17 | 1. Standard: _standard_ 18 | - _link to docs_ 19 | - ... 20 | 2. Standard: _standard_ 21 | - _link to docs_ 22 | - ... 23 | 1. Technique: _technique_ 24 | - _link to docs_ 25 | - ... 26 | 2. Technique: _technique_ 27 | - _link to docs_ 28 | - ... 29 | 30 | ### Summary of research on standards and leading techniques 31 | #### Relevant standards and techniques exist? 32 | #### Those intended to follow (and why) 33 | #### Those intended to ignore (and why) 34 | 35 | ## 3. Research of libraries from other languages 36 | 37 | 1. Language: Go 38 | - [html](http://golang.org/pkg/html/) 39 | - `EscapeString()` escapes only the 5 characters `< > & ' "` 40 | - `UnescapeString()` unescapes more characters 41 | 1. Language: PHP 42 | - [htmlspecialchars()](http://php.net/manual/en/function.htmlspecialchars.php) 43 | - escapes only the 5 characters `< > & ' "` 44 | - [htmlspecialchars_decode ()](http://www.php.net/manual/en/function.htmlspecialchars-decode.php) 45 | - decodes only the characters handled by htmlspecialchars() 46 | 1. Language: RUby 47 | - [CGI.escapeHTML](http://www.ruby-doc.org/stdlib-1.9.3/libdoc/cgi/rdoc/CGI.html#method-c-escapeHTML) 48 | - escapes only the 5 characters `< > & ' "` 49 | - [CGI.unescapeHTML](http://www.ruby-doc.org/stdlib-1.9.3/libdoc/cgi/rdoc/CGI.html#method-c-unescapeHTML) 50 | - [htmlentities gem](https://github.com/threedaymonk/htmlentities) 51 | 52 | ### Summary of research from other languages: 53 | #### Structures and functions commonly appearing 54 | #### Variations on implementation seen 55 | #### Pitfalls and hazards associated with each variant 56 | #### Relationship to other libraries and/or abstract interfaces 57 | 58 | ## 4. Module writing 59 | 60 | See https://github.com/veddan/rust-htmlescape 61 | 62 | - Pull request: _link to bug_ 63 | 64 | ### Additional implementation notes 65 | 66 | Question: where to get from the complete list of characters to escape and entities to produce? 67 | 68 | - `escape_minimal()` only escapes the necessary 5 characters `< > & ' "` which are necessary for security/forms/URLs 69 | - `<` => `<` 70 | - `>` => `>` 71 | - `&` => `&` 72 | - `'` => `'` 73 | - `"` => `"` 74 | - `escape_full()` escapes all characters 75 | - We probably should use a table-lookup (binary search), similar to the code in https://github.com/mozilla/rust/blob/incoming/src/libcore/unicode.rs -------------------------------------------------------------------------------- /Lib-fmt.md: -------------------------------------------------------------------------------- 1 | Module editing plan template 2 | 3 | ## 1. Announcement to mailing list 4 | 5 | - Proposed editor: _your name_ 6 | - Date proposed: _date of proposal_ 7 | - Link: _link to email_ 8 | 9 | ### Notes from discussion on mailing list 10 | 11 | - ["RFC: User-implementable format specifiers w/ compile-time checks"](https://mail.mozilla.org/pipermail/rust-dev/2013-May/003999.html) 2013-05-03 12 | - ["Redesigning fmt!"](https://mail.mozilla.org/pipermail/rust-dev/2013-July/004961.html) 2013-07-26 13 | - Some notes in ["bikeshedding println() and friends"](https://mail.mozilla.org/pipermail/rust-dev/2013-July/004836.html) 14 | 15 | ## 2. Research of standards and techniques 16 | 17 | 1. Standard: _standard_ 18 | - _link to docs_ 19 | - ... 20 | 2. Standard: _standard_ 21 | - _link to docs_ 22 | - ... 23 | 1. Technique: ICU/Java-stype MessageFormat 24 | - http://www.icu-project.org/apiref/icu4j/com/ibm/icu/text/MessageFormat.html 25 | - http://docs.oracle.com/javase/1.4.2/docs/api/java/text/MessageFormat.html 26 | 27 | ### Summary of research on standards and leading techniques 28 | #### Relevant standards and techniques exist? 29 | #### Those intended to follow (and why) 30 | 31 | Something like the MessageFormat specifier should be our default, given that it's the leading approach to the needs of i18n. 32 | 33 | #### Those intended to ignore (and why) 34 | 35 | ## 3. Research of libraries from other languages 36 | 37 | 1. Language: C++ 38 | - [boost format](http://www.boost.org/doc/libs/1_53_0/libs/format/) 39 | 2. Language: Java 40 | - [java.text.MessageFormat](http://docs.oracle.com/javase/1.4.2/docs/api/java/text/MessageFormat.html) 41 | - [java.util.Formatter](http://docs.oracle.com/javase/6/docs/api/java/util/Formatter.html) 42 | 3. Language: Common Lisp 43 | - [Format](http://www.lispworks.com/documentation/HyperSpec/Body/22_c.htm) 44 | 4. Language: Python 3 45 | - [Format strings](http://docs.python.org/3/library/string.html#formatstrings) 46 | 5. Language: C/POSIX 47 | - [ICU MessageFormat](http://userguide.icu-project.org/formatparse/messages) 48 | - [Printf](http://pubs.opengroup.org/onlinepubs/9699919799/functions/printf.html) 49 | 6. Language: C#/.NET 50 | - [Formatting types](http://msdn.microsoft.com/en-us/library/26etazsy.aspx) 51 | 7. Language: Go 52 | - [go.fmt](http://golang.org/pkg/fmt/) 53 | 8. Language: JS 54 | - [MessageFormat.js](https://github.com/SlexAxton/messageformat.js) 55 | 56 | 57 | ### Summary of research from other languages: 58 | #### Structures and functions commonly appearing 59 | #### Variations on implementation seen 60 | #### Pitfalls and hazards associated with each variant 61 | #### Relationship to other libraries and/or abstract interfaces 62 | 63 | ## 4. Module writing 64 | 65 | - Pull request: _link to bug_ 66 | 67 | ### Additional implementation notes 68 | 69 | - _note_ 70 | - _note_ 71 | - _note_ -------------------------------------------------------------------------------- /Meeting-API-review-2014-06-23.md: -------------------------------------------------------------------------------- 1 | # 2014-06-23 2 | 3 | # Attending 4 | 5 | luqman, cmr, brson, aturon, acrichto, bjz, niko, nrc, pcwalton 6 | 7 | # clone 8 | 9 | https://github.com/rust-lang/rust/blob/master/src/libcore/clone.rs 10 | 11 | - Notable: `clone` takes `&self`, not `&mut self` 12 | - Concerns: Utility of clone_from. Implemented by Vec. 13 | - Impls for `&'a T`, `&'a [T]`, `&'a str`, primitives 14 | - Impls for `extern "Rust" fn` 15 | - Recommendation: call the whole thing unstable 16 | 17 | - Declare these unstable: 18 | 19 | - impl clone for primitives 20 | - ../src/libcore/tuple.rs:107: impl<$($T:Clone),+> Clone for ($($T,)+) { 21 | - ../src/libcore/cell.rs:195:impl Clone for Cell { 22 | - ../src/libcore/cell.rs:301:impl Clone for RefCell { 23 | - ../src/libcore/clone.rs:42:impl<'a, T> Clone for &'a T { 24 | - ../src/libcore/clone.rs:48:impl<'a, T> Clone for &'a [T] { 25 | - ../src/libcore/clone.rs:54:impl<'a> Clone for &'a str { 26 | - ../src/liballoc/rc.rs:146:impl Clone for Rc { 27 | - ../src/liballoc/rc.rs:227:impl Clone for Weak { 28 | - ../src/liballoc/arc.rs:113:impl Clone for Arc { 29 | - ../src/liballoc/arc.rs:239:impl Clone for Weak { 30 | - ../src/liballoc/owned.rs:45:impl Clone for Box { 31 | - ../src/libcollections/vec.rs:315:impl Clone for Vec { 32 | - ../src/libstd/gc.rs:40:impl Clone for Gc { 33 | 34 | nmatsakis: cloning for fns is not good. might want to be careful. doesn't handle bound lifetimes correctly. 35 | 36 | ``` 37 | <'a> fn(x: &'a Foo) -> &'a uint 38 | 39 | fn(T) -> U 40 | ``` 41 | 42 | nmatsakis: clone will just fail - has to match to a template. will for for specific lifetimes, but not for generic lifetimes 43 | 44 | ``` 45 | impl Clone for T { 46 | fn clone(&self) -> T { 47 | } 48 | } 49 | ``` 50 | 51 | acrichto: don't think that is possible. with tuples, if first is copyable, second is not,... 52 | nmatsakis: yeah, painful for tuples. 53 | nmatsakis: not crazy about clone for functions 54 | 55 | aturon: do we plan on making a second pass? 56 | brson: yes. 57 | 58 | ## action items 59 | 60 | - clone_from experimental 61 | - extern fns experimental 62 | - everything else unstable 63 | - make listed imples unstable 64 | 65 | # bool 66 | 67 | https://github.com/rust-lang/rust/blob/master/src/libcore/bool.rs 68 | 69 | - Remove to_bit 70 | - Move tests into run-pass as basic language tests 71 | - Leave module intact for docs (for now) 72 | - Module is unstable (or experimental if we are unsure about docs) 73 | - make bool module cfg(docs) 74 | 75 | # uint 76 | 77 | https://github.com/rust-lang/rust/blob/master/src/libcore/num/uint_macros.rs 78 | https://github.com/rust-lang/rust/blob/master/src/libcore/num/int.rs 79 | https://github.com/rust-lang/rust/blob/master/src/libstd/num/int_macros.rs 80 | 81 | 82 | ## action items 83 | 84 | - parse_bytes, FromStr, FromStrRadix experimental - may want to use result 85 | - deprecate to_str_bytes 86 | - deprecate ToStrRadix 87 | -------------------------------------------------------------------------------- /OS-Bridge-2013-tutorial.md: -------------------------------------------------------------------------------- 1 | These are Tim's notes for a proposed Rust tutorial at [Open Source Bridge](http://opensourcebridge.org/) 2013. 2 | 3 | Length: 1 hour, 45 minutes. 15 minutes for Q & A; plan for 90 minutes. ~ 45 slides, two minutes per slide. 4 | 5 | Examples: Look at Servo (resource manager, display list...), https://github.com/pcwalton/fempeg , https://github.com/pcwalton/sprocketnes , ... 6 | 7 | * What is Rust? (4 slides) 8 | * Why another programming language? 9 | * For systems programming, want a straightforward mapping between language semantics and machine, like what C gives you. 10 | * For writing safe and reliable applications, don't want buffer overflows, null pointers, or other preventable vulnerabilities. 11 | * For taking advantage of modern hardware, want usable concurrency constructs (not the focus of this talk) 12 | * In general, want types and pattern matching, without the overhead of functional languages like Haskell and ML (but we pay the price of having to think more about memory allocation and data representations than in those languages) 13 | * Fun with types (4 slides) 14 | * Algebraic data types (simple example) 15 | * Generics (ditto) 16 | * Pattern matching 17 | * Structs: named product types 18 | * Field access, functional record update 19 | * Using traits (4 slides) 20 | * intro to traits (simple example) 21 | * trait inheritance 22 | * default methods 23 | * objects / dynamic dispatch 24 | * the difference between static and dynamic dispatch 25 | * Could start with a program that duplicates code, and show how traits emerge when refactoring it 26 | * Background on traits (2 slides) 27 | * Traits vs. type classes 28 | * Traits vs. OO classes 29 | * bringing together OO & functional styles 30 | * Pointers and memory in Rust (10 slides) 31 | (example for each) 32 | * In Java, Haskell, ... , everything (except for a few primitive types) is implicitly boxed, and you can't explicitly create/dereference pointers 33 | * Not so in Rust: in fact, we have three kinds of pointers 34 | * Shared (@) 35 | * Unique (~) 36 | * @ is garbage-collected, ~ gets freed automatically because the compiler knows its lifetime 37 | * You can send ~ in between tasks (haven't introduced tasks yet) 38 | * Borrowed (&) 39 | * Interior pointers 40 | * Returning a borrowed pointer into a structure 41 | * The important thing is that this is all safe: no dangling pointers, no leaks. (except with unsafe code or compiler/RT bugs, handwave handwave) 42 | (24 slides so far) 43 | * A more extended example combining traits and pointers? (4 slides) 44 | * A more extended example exhibiting borrowed pointers? (4 slides) 45 | * Miscellaneous fun stuff (4 slides): 46 | * #[test] 47 | * #[bench] 48 | * fmt! (nod to macros in general); deriving-eq? 49 | * (what else?) 50 | * Concurrency (3 slides) (maybe... very simple in any case) 51 | * example (maybe from one of the shootout benchmarks) 52 | 39 so far 53 | * Demonstrate changing a simple program with @-boxes into something with no GC? Show stats for amount of memory allocated? 54 | * Questions? -------------------------------------------------------------------------------- /Note-guide-for-new-contributors.md: -------------------------------------------------------------------------------- 1 | You want to contribute to Rust? Frankly, you've made an excellent decision. Rust is developed by a small and inclusive community that takes *very kindly* to strangers. You are going to have a good time. 2 | 3 | The way [many people][cmr] seem to get involved is by simply trying to write Rust code. Inevitably they hit a bug or missing feature, at which point they are compelled to [[write a patch|Note development policy]]. 4 | 5 | We coordinate through [discuss.rust-lang.org][discuss], [IRC][pound-rust-internals], and the GitHub [issue] tracker. 6 | 7 | [cmr]: http://cmr.github.io/blog/2013/06/23/how-i-got-started-with-rust/ 8 | [pound-rust-internals]: http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-internals 9 | [r/rust]: http://reddit.com/r/rust 10 | [issue]: http://github.com/mozilla/rust/issues 11 | [discuss]: http://discuss.rust-lang.org 12 | 13 | ## Hacking on Rust 14 | 15 | Before hacking, read some tips on [[getting started|Note-getting-started-developing-rust]] and the [[development policy|Note-development-policy]]. The [[Notes]] section on the wiki contains general wisdom about the code base from other developers. 16 | 17 | ## Picking something to do 18 | 19 | The simplest way is to look through the [issue tracker] for issues labeled with "E-easy", "I-enhancement", "I-wishlist", and/or "A-an-interesting-project". Unassigned bugs are always fair game. Assigned bugs that don't seem to be getting worked on actively can be fair game, but always check with the bug owner first in that case. 20 | 21 | Outstanding bugs or feature requests in Rust often have a corresponding test in the [[test suite|Note testsuite]] that doesn't yet pass. One good way to jump into Rust development is to look for files in the test/run-pass directory containing the string `ignore-`. Those tests all correspond to bugs that need to be fixed, features that someone needs to finish, or sometimes tests that need deleting. 22 | 23 | The source is also littered with hundreds of comments marked with 'FIXME'. In Rust, many FIXME comments come with an issue number; sometimes these refer to issues that may be resolved easily. 24 | 25 | Another easy way to get involved is to participate in bug triage. Every week we send out lists of bugs to contributors along with instructions on how to move them forward. If you would like to participate email Brian at banderson@mozilla.com. 26 | 27 | 28 | If in doubt, ask on IRC. Somebody will surely have a task that needs to be done. 29 | 30 | ## Ideas for newbies 31 | 32 | * Adopt a module in std and ensure all doc comments are provided, accurate, complete and follow the [style guidelines](http://aturon.github.io/style/comments.html). 33 | * Adopt a module and write unit tests for each feature. Bonus points for writing one that triggers a bug and reporting it. 34 | * Examine the runtime library of language Xyz and build a table comparing features with Rust, identifying missing features. 35 | * Proofread the Guide, ensuring it works as described with the relevant release of the compiler. 36 | 37 | Reddit has [more ideas still](http://www.reddit.com/r/rust/comments/1grj61/feed_us_some_low_hanging_fruit/). 38 | 39 | [issue tracker]: http://github.com/mozilla/rust/issues 40 | [contributing]: https://github.com/mozilla/rust/blob/master/CONTRIBUTING.md 41 | -------------------------------------------------------------------------------- /Anticipated-breaking-changes-during-1.0-alpha.md: -------------------------------------------------------------------------------- 1 | # Where do we anticipate breakage during alpha? 2 | 3 | ## To *unstable* APIs: 4 | 5 | Any unstable API may change, but the big changes we expect are: 6 | 7 | * **Path reform:** The `path` module will soon be [reformed](https://github.com/rust-lang/rfcs/pull/474) to make use of DST, to give a better account of platform differences, and to more closely align with the [new C++ standard](http://article.gmane.org/gmane.comp.lib.boost.devel/256220). Implementation work is largely complete, and the rollout should occur soon after alpha. 8 | 9 | * **IO reform:** An [overhaul of the IO APIs](https://github.com/rust-lang/rfcs/pull/517/) is being planned; please join in the conversation! These changes will be landing throughout the alpha cycle. 10 | 11 | ## To *stable* APIs/language features: 12 | 13 | ### Stable libraries 14 | 15 | - *Integer auditing:* with the move away from int/uint, we need to establish formal conventions for integer type choices and roll them out. This will affect some stable APIs, but we will likely add some form of widening to limit the breakage. 16 | 17 | - *Overflow semantics:* we plan to introduce [overflow checking in debug builds](https://github.com/rust-lang/rfcs/pull/560). 18 | 19 | - *Send/Sync changes:* to allow threads to share stack data, we are considering [removing 'static from Send](https://github.com/rust-lang/rfcs/pull/458), probably accompanied by some shorthand for trait objects that should minimize breakage. 20 | 21 | ### Destructors 22 | 23 | * *Unsafe destructors:* closing [some holes](https://github.com/rust-lang/rust/issues/8861) and ungating unsafe destructors may cause minor breakage. 24 | 25 | * *Dynamic-drop restrictions:* We are switching to a scheme that uses [lightweight flags on the stack](https://github.com/rust-lang/rfcs/pull/320) to determine whether a value must be dropped rather than zeroing out memory. This implies some [small restrictions](https://github.com/rust-lang/rfcs/pull/533) on what moves are permitted relative to today. 26 | 27 | ### DST 28 | 29 | - *Sized:* the default assumptions about whether type parameters are sized continue to be tweaked, and we hope to try an [inference scheme](http://smallcultfollowing.com/babysteps/blog/2014/07/06/implied-bounds/) for them, which may result in some minor breakage. 30 | 31 | ### Notation tweaks 32 | 33 | - *`for` loops:* loops will change to take ownership of the iterator, in preparation for `IntoIterator` (or perhaps move directly to `IntoIterator`). This can be trivially worked around by using `by_ref`. 34 | 35 | - *Closure types:* we hope to remove the `:` notation for closures in favor of [capture clause inference](https://github.com/rust-lang/rfcs/blob/master/text/0231-upvar-capture-inference.md). 36 | 37 | - *Indexing notation*: either change to take the index by value (unlikely) or to include `IndexSet` (more likely). 38 | 39 | ### Traits and type system 40 | 41 | - *Coherence:* we will continue to improve the coherence rules (e.g. [the orphan rule](https://github.com/rust-lang/rust/issues/19470)), although this will probably not break existing code but rather allow more code to work. 42 | 43 | - *Subtyping:* some details of coercion and subtyping \[[1](https://github.com/rust-lang/rust/issues/18737), [2](https://github.com/rust-lang/rfcs/issues/281)\] are likely to be tweaked. We do not anticipate significant breakage here. 44 | 45 | 46 | -------------------------------------------------------------------------------- /Doc-under-construction-FAQ.md: -------------------------------------------------------------------------------- 1 | This page serves as a quick reference for certain corner-cases of the language where it's not obvious how to make the compiler stop complaining at you. 2 | 3 | ## Once functions 4 | 5 | **Why can't closures move out of captured variables?** 6 | 7 | Consider the following code: 8 | ``` 9 | fn foo(message: ~str, chan_opt: Option>) { 10 | do chan_opt.map |chan| { 11 | // error: cannot move out of captured outer variable 12 | chan.send(message); 13 | // ^~~~~~~ 14 | } 15 | } 16 | ``` 17 | This code should be legal, because the closure provided to ```map_consume``` will only be called once, so it's just as if ```message``` were moved out without a closure being involved. However, the compiler can't distinguish that case from this one: 18 | ``` 19 | fn foo(message: ~str, chan_list: ~[Chan<~str>]) { 20 | do chan_list.map |chan| { 21 | // XXX: might unsafely duplicate the unique message pointer! 22 | chan.send(message); 23 | } 24 | } 25 | ``` 26 | **Recommended solution:** To work around this problem, you could either use an alternate higher-order function that accepts an additional argument to pass through: 27 | ``` 28 | fn foo(message: ~str, chan_opt: Option>) { 29 | do chan_opt.map_with(message) |message, chan| { 30 | chan.send(message); 31 | } 32 | } 33 | ``` 34 | ...or, if no such alternate exists, use the ```std::cell::Cell``` type: 35 | ``` 36 | fn foo(message: ~str, chan_opt: Option>) { 37 | let message_cell = Cell::new(message); 38 | do chan_opt.map |chan| { 39 | // NOTE: If the closure is called twice, the 2nd take() will fail! 40 | chan.send(message_cell.take()); 41 | } 42 | } 43 | ``` 44 | We are prototyping a language feature called *one-shot functions*, where you can write the type of a closure as ```&once fn()``` or ```~once fn()```, to indicate that the closure must be consumed when called, so it can safely move out of its environment. Currently you can enable this by compiling with ```rustc -Z once-fns```, but this is not likely to be enabled by default in the 1.0 release. 45 | 46 | 47 | ## Noncopyable stack closures 48 | 49 | **Why can't I use my stack closure multiple times (rustc says, "moved by default, use copy to override")?** 50 | 51 | You may have seen this error if you have code along the lines of: 52 | ``` 53 | fn bar(callback: &fn(int)) { 54 | baz(13, callback); 55 | callback(37); // error: use of moved value 56 | } 57 | ``` 58 | or: 59 | ``` 60 | fn bar(vec: &[int], callback: &fn(int)) { 61 | for vec.each |x| { 62 | baz(x, callback); // error: cannot move out of captured outer variable 63 | } 64 | } 65 | ``` 66 | The compiler issues this error because while it's safe to *call* ```&fn()```s multiple times, it is not safe to *copy* them. (Allowing arbitrary stack closures to be copied would [break soundness](http://smallcultfollowing.com/babysteps/blog/2013/04/30/the-case-of-the-recurring-closure/) in certain cases.) 67 | 68 | **Recommended solution:** To work around this error, "borrow" the closure by capturing it in another closure, like so: 69 | ``` 70 | fn bar(callback: &fn(int)) { 71 | baz(13, |x| callback(x)); // callback temporarily captured, but not moved 72 | callback(37); // ok 73 | } 74 | ``` 75 | In the future we hope to automatically perform such borrows, so the original code will be legal again. -------------------------------------------------------------------------------- /Rustpkg-schedule.md: -------------------------------------------------------------------------------- 1 | This is a schedule for getting rustpkg to the point where we can build Servo with it, keeping in mind that like any package, rustpkg will never be complete. The goal is to reach the standard of quality implied by the issues up to and including those on Milestone 5 being complete. 2 | 3 | Previous discussions about rustpkg planning: 4 | * https://etherpad.mozilla.org/Meeting-weekly-2013-08-27 5 | 6 | ## First 10 servo crates: 9/11/2013 7 | * ~~[#7075](https://github.com/mozilla/rust/issues/7075) - workcache~~ 8 | * ~~[#8522](https://github.com/mozilla/rust/issues/8522) - rustc flags~~ - 9/11/2013 9 | 10 | ## Build all of servo: 10/1/2013 11 | * ~~[#6408](https://github.com/mozilla/rust/issues/6408) - pkgids with subdirs~~ - 9/16/2013 (medium) 12 | * ~~[#8524](https://github.com/mozilla/rust/issues/8524) - recursive dependencies~~ - 9/18/2013 (easy) 13 | * ~~[#7402](https://github.com/mozilla/rust/issues/7402) - install to RUST_PATH~~ - 9/19/2013 (easy) 14 | * ~~Tim on PTO, 9/20~~ 15 | * ~~[#7879](https://github.com/mozilla/rust/issues/7879) - infinite loop compiling dependencies~~ - 9/24/2013 (hard) 16 | * ~~[#9112](https://github.com/mozilla/rust/issues/9112) - install doesn't depend on build~~ - 9/26/2013 17 | * ~~[#7401](https://github.com/mozilla/rust/issues/7242) - remaining rustpkg commands; *just* `test` for now~~ - 9/27/2013 (medium) 18 | * ~~[#6403](https://github.com/mozilla/rust/issues/6403) - building c libs~~ - 9/30/2013 (medium) 19 | * ~~[#8672](https://github.com/mozilla/rust/issues/8672) - target specific output directory~~ - 10/1/2013 (easy) 20 | 21 | ## Community adoption I: 10/29/2013 22 | * ~~[#6480](https://github.com/mozilla/rust/issues/6480) - make locally-cached files read only~~ - 10/3/2013 (easy) 23 | * ~~Mozilla Summit, 10/4-10/7~~ 24 | * ~~[#8520](https://github.com/mozilla/rust/issues/8520) - find sources in $CWD - 10/10/2013~~ (medium) 25 | * ~~[#9193](https://github.com/mozilla/rust/issues/9193) - remote packages regression~~ - 10/12/2013 (medium) 26 | * [#7240](https://github.com/mozilla/rust/issues/7240) - multi-crate packages - 10/17/2013 (hard) 27 | * [#8711](https://github.com/mozilla/rust/issues/8711) - correctly deal with versions of installed pkgs - 10/22/2013 (medium) 28 | * ~~Tim on PTO, 10/23/2013~~ 29 | * ~~[#9045](https://github.com/mozilla/rust/issues/9045) - rustpkg init (graydon's .rust_workspace suggestion)~~ (Implemented by @steveklabnik) - 10/29/2013 (medium) 30 | 31 | ## Community adoption II: 12/5/2013 32 | * Tim on PTO, 11/1/2013 33 | * [#7401](https://github.com/mozilla/rust/issues/7401) - support custom commands - 11/6/2013 (hard) 34 | * [#6365](https://github.com/mozilla/rust/issues/6365) - usage messages - 11/7/2013 (easy) 35 | * [#8892](https://github.com/mozilla/rust/issues/8892) - suppress installation of some crate files (the "glfw/examples" problem) - 11/12/2013 (medium) 36 | * [#8405](https://github.com/mozilla/rust/issues/8405) - semantic versions - 11/20/2013 (hard) 37 | * [#7242](https://github.com/mozilla/rust/issues/7242) - finish all commands - 11/27/2013 (particularly `do` and `info`) (hard) 38 | * Thanksgiving holiday 11/28-11/29 39 | * [#6005](https://github.com/mozilla/rust/issues/6005) - rustdoc integration - 12/5/2013 (hard) 40 | 41 | ## Everything else (To be scheduled once community adoption is complete or close to complete) 42 | * #7447 - version improvements 43 | * #3346 - crate name in log map 44 | * ~~#6409 - API for `git clone`~~ 45 | * #6410 - libgit2 bindings 46 | * #1453 - continuous integration server 47 | * #1642 - continuous documentation server 48 | * #5219 - rpath 49 | * #2124 - bindgen 50 | * #8523 - forbid linkage attributes for rustpkg crates 51 | * #8673 - extern mod duplication 52 | * #6481 - lint command 53 | * #7744 - error handling with bad package IDs 54 | * #2219 - --attr flag 55 | * #8871 - where to install remote packages (needstest) 56 | * #8952 - executable naming 57 | * #7243 - unpacking tarball packages, fetching via curl 58 | * #9003 - `rustpkg test` cleanup -------------------------------------------------------------------------------- /Note-research.md: -------------------------------------------------------------------------------- 1 | Papers that have had more or less influence on Rust, or which one might want to consult for inspiration or to understand Rust's background. 2 | 3 | ## Type system 4 | 5 | * [Region based memory management in Cyclone](http://209.68.42.137/ucsd-pages/Courses/cse227.w03/handouts/cyclone-regions.pdf) 6 | * [Safe manual memory management in Cyclone](http://www.cs.umd.edu/projects/PL/cyclone/scp.pdf) 7 | * [Typeclasses: making ad-hoc polymorphism less ad hoc](http://www.ps.uni-sb.de/courses/typen-ws99/class.ps.gz) 8 | * [Macros that work together](https://www.cs.utah.edu/plt/publications/jfp12-draft-fcdf.pdf) 9 | * [Traits: composable units of behavior](http://scg.unibe.ch/archive/papers/Scha03aTraits.pdf) 10 | * [Alias burying](http://www.cs.uwm.edu/faculty/boyland/papers/unique-preprint.ps) - We tried something similar and abandoned it. 11 | * [External uniqueness is unique enough](http://www.computingscience.nl/research/techreps/repo/CS-2002/2002-048.pdf) 12 | * [Uniqueness and Reference Immutability for Safe Parallelism](https://research.microsoft.com/pubs/170528/msr-tr-2012-79.pdf) 13 | * [Region Based Memory Management](http://www.cs.ucla.edu/~palsberg/tba/papers/tofte-talpin-iandc97.pdf) 14 | 15 | ## Concurrency 16 | 17 | * [Singularity: rethinking the software stack](https://research.microsoft.com/pubs/69431/osr2007_rethinkingsoftwarestack.pdf) 18 | * [Language support for fast and reliable message passing in singularity OS](https://research.microsoft.com/pubs/67482/singsharp.pdf) 19 | * [Scheduling multithreaded computations by work stealing](http://supertech.csail.mit.edu/papers/steal.pdf) 20 | * [Thread scheduling for multiprogramming multiprocessors](http://www.eecis.udel.edu/%7Ecavazos/cisc879-spring2008/papers/arora98thread.pdf) 21 | * [The data locality of work stealing](http://www.aladdin.cs.cmu.edu/papers/pdfs/y2000/locality_spaa00.pdf) 22 | * [Dynamic circular work stealing deque](http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.170.1097&rep=rep1&type=pdf) - The Chase/Lev deque 23 | * [Work-first and help-first scheduling policies for async-finish task parallelism](http://www.cs.rice.edu/%7Eyguo/pubs/PID824943.pdf) - More general than fully-strict work stealing 24 | * [A Java fork/join calamity](http://www.coopsoft.com/ar/CalamityArticle.html) - critique of Java's fork/join library, particularly its application of work stealing to non-strict computation 25 | * [Scheduling techniques for concurrent systems](http://www.ece.rutgers.edu/%7Eparashar/Classes/ece572-papers/05/ps-ousterhout.pdf) 26 | * [Contention aware scheduling](http://www.blagodurov.net/files/a8-blagodurov.pdf) 27 | * [Balanced work stealing for time-sharing multicores](http://www.cse.ohio-state.edu/hpcs/WWW/HTML/publications/papers/TR-12-1.pdf) 28 | * [Three layer cake](http://www.upcrc.illinois.edu/workshops/paraplop10/papers/paraplop10_submission_8.pdf) 29 | * [Non-blocking steal-half work queues](http://www.cs.bgu.ac.il/%7Ehendlerd/papers/p280-hendler.pdf) 30 | * [Reagents: expressing and composing fine-grained concurrency](http://www.mpi-sws.org/~turon/reagents.pdf) 31 | * [Algorithms for scalable synchronization of shared-memory multiprocessors](https://www.cs.rochester.edu/u/scott/papers/1991_TOCS_synch.pdf) 32 | 33 | ## Other 34 | 35 | * [Crash-only software](https://www.usenix.org/legacy/events/hotos03/tech/full_papers/candea/candea.pdf) 36 | * [Composing High-Performance Memory Allocators](http://people.cs.umass.edu/~emery/pubs/berger-pldi2001.pdf) 37 | * [Reconsidering Custom Memory Allocation](http://people.cs.umass.edu/~emery/pubs/berger-oopsla2002.pdf) 38 | 39 | ## Papers *about* Rust 40 | 41 | * [GPU programming in Rust](http://www.cs.indiana.edu/~eholk/papers/hips2013.pdf) 42 | * [Parallel closures: a new twist on an old idea](https://www.usenix.org/conference/hotpar12/parallel-closures-new-twist-old-idea) - not exactly about rust, but by nmatsakis 43 | * [Patina: A Formalization of the Rust Programming Language](ftp://ftp.cs.washington.edu/tr/2015/03/UW-CSE-15-03-02.pdf) 44 | 45 | Missing topics: L4, linear types, typestate 46 | -------------------------------------------------------------------------------- /Doc-packages,-editors,-and-other-tools.md: -------------------------------------------------------------------------------- 1 | ## Packages 2 | 3 | * FreeBSD 4 | * [FreeBSD Port](http://www.freebsd.org/cgi/cvsweb.cgi/ports/lang/rust/) - maintained by jyyou 5 | * Linux 6 | * [Arch Linux Official](https://www.archlinux.org/packages/community/x86_64/rust/) 7 | * [Arch Linux Nightly Build Repository](http://pkgbuild.com/~thestinger/repo/) 8 | * [Fedora Copr](http://copr-fe.cloud.fedoraproject.org/coprs/fabiand/rust-unofficial/) - ([instructions](http://dummdida.blogspot.de/2013/05/mozillas-rust-in-fedoras-ppa-copr.html)) maintained by fabiand 9 | * [Ubuntu PPA](https://launchpad.net/~hansjorg/+archive/rust) 10 | * [Gentoo, overlay rust](https://github.com/Heather/gentoo-rust) 11 | * Mac 12 | * [Fink](http://fink.cvs.sourceforge.net/viewvc/fink/dists/10.7/stable/main/finkinfo/languages/rust.info?view=log) Also available through fink's apt at `deb http://brendan.users.finkproject.org/10.8 stable main` - maintained by bcully 13 | * [Homebrew](https://github.com/mxcl/homebrew/blob/master/Library/Formula/rust.rb) 14 | * [Homebrew Cask](https://github.com/caskroom/homebrew-cask/blob/master/Casks/rust.rb) 15 | * NetBSD 16 | * [pkgsrc-wip](http://pkgsrc-wip.cvs.sourceforge.net/viewvc/pkgsrc-wip/wip/rust/) 17 | * Windows 18 | * [NuGet package for nightly builds](https://www.nuget.org/packages/Rust/) 19 | * [[How to install an unofficial nightly for Windows|Doc how to install an unofficial nightly for Windows]] 20 | 21 | ## Editors 22 | 23 | * BBEdit 24 | * [Erik Rose's BBEdit plugin](https://github.com/erikrose/rust-bbedit-plugin) - Plugin for BBEdit. Probably quite out of date. 25 | * Eclipse 26 | * [ianb's Eclipse plugin](https://github.com/ianbollinger/oxide) - Eclipse! (dead) 27 | * [Reidar Sollid's Eclipse plugin](https://github.com/reidarsollid/RustyCage) - A newer Eclipse plugin. 28 | * Emacs 29 | * [rust-mode](https://github.com/rust-lang/rust-mode). 30 | * Flycheck has support for on-the-fly syntax error detection. Use the Package Manager (ELPA) to install `flycheck-mode` 31 | * Geany 32 | * Since 1.24. [Nightly builds](http://nightly.geany.org/) or the [git master](https://github.com/geany/geany) may have additional improvements. 33 | * Gedit 34 | * included, see `src/etc/` 35 | * Intellij 36 | * [Vektah's Intellij plugin] (http://plugins.jetbrains.com/plugin/7438) - Can be installed from Plugins settings in app 37 | * Kate 38 | * [Rust Kate Config](https://github.com/rust-lang/kate-config) (the file can be copied or linked to ~/.kde/share/apps/katepart/syntax/ for KDE4 or ~/.local/share/katepart5/syntax/ for KF5) 39 | * Netbeans 40 | * [Rust NetBeans 8+ Plugin](https://github.com/azazar/rust-netbeans) - Forked drrb's NetBeans Plugin 41 | * [drrb's NetBeans Plugin](https://github.com/drrb/rust-netbeans) - Rust NetBeans Plugin 42 | * SublimeText 43 | * [kib2's SublimeText2 language file](http://kib2.free.fr/Falcon/blog/25-01-2012-SublimeText2-Rust.html) - Highlighting for SublimeText 2 44 | * [dbp's SublimeText2 (now maintained by jhasse)](https://github.com/jhasse/sublime-rust) - Probably more up to date than the above. 45 | * [SublimeLinter plugin](https://github.com/oschwald/SublimeLinter-contrib-rustc) 46 | * TextMate 47 | * [tomgrohl's textmate bundle](https://github.com/tomgrohl/Rust.tmbundle) - TextMate 1 48 | * [elia's textmate bundle](https://github.com/elia/rust.tmbundle) - TextMate 2 49 | * Textadept 50 | * [abaez's Textadept module/lexer](https://bitbucket.org/a_baez/ta-rust) 51 | * [suhr/ta-rust](https://github.com/suhr/ta-rust) 52 | * Vim 53 | * [rust.vim plugin](https://github.com/rust-lang/rust.vim). Syntastic has syntax error matching based on rustc. 54 | * NEdit 55 | * [NEdit syntax highlighting for Rust](https://mail.mozilla.org/pipermail/rust-dev/2013-September/005822.html) 56 | * Notepad++ 57 | * [Notepad++ syntax highlighting](https://github.com/pfalabella/Rust-notepadplusplus) 58 | * Brackets 59 | * [Brackets syntax highlighting for Rust](https://github.com/frozzare/brackets-rust) 60 | * Atom 61 | * [Atom Racer : intelligent code completion for Rust based on Racer](https://github.com/edubkendo/atom-racer) 62 | * [Atom Rust: Syntax highlighting, snippets, etc](https://github.com/zargony/atom-language-rust) 63 | 64 | ## And more! 65 | 66 | * [cargo-lite](https://github.com/cmr/cargo-lite) - A simple package manager 67 | * [Prism's pastebin](http://kib2.free.fr/pastebin) - A pastebin instance that support Rust syntax highlighting using the Prism library 68 | * [startling's pygments plugin](https://github.com/startling/pygments-rust) - Pygments syntax highlighting 69 | * [GitHub linguist](https://github.com/github/linguist) - GitHub's language detection supports Rust 70 | * [lkuper's PLT Redex model](https://github.com/lkuper/rust-redex) - An (out-of-date) model of Rust in PLT Redex 71 | * [highlight.js](http://softwaremaniacs.org/soft/highlight/en/) - Highlight Rust code in your blog by adding a single line of JavaScript to your pages 72 | * [bstrie's map of Rust contributors](http://seleniac.org/map/) 73 | * ["Is Rust fast yet?"](http://huonw.github.io/isrustfastyet/) - graphs of the build/test times of each merge into incoming -------------------------------------------------------------------------------- /Note-git-workflow.md: -------------------------------------------------------------------------------- 1 | Incoming 2 | -------- 3 | 4 | * The integration branch is `master`. Only the sheriff should push to `master`. 5 | * Integration happens automatically via @bors. This is an automatic integration robot that does the entire merge-and-test integration cycle after an authorized reviewer reviews your pull request. 6 | 7 | General 8 | ------- 9 | 10 | When submitting pull requests it is important to know your branch may be rebased, which will change its history and make your branch's history invalid. 11 | 12 | One possible workflow that has worked for developers on the project is outlined below. This assumes that you have an 'origin' remote that represents your remote github repo (i.e. your github-hosted fork of `rust-lang/rust`), and a 'upstream' remote that represents rust-lang's. 13 | The 'origin' remote is set when you make the initial clone of your fork. 14 | To create the 'upstream' remote, you can execute: 15 | ``` 16 | $ git remote add upstream https://github.com/rust-lang/rust 17 | ``` 18 | 19 | 1. Whenever you start working on anything new, create a new branch derived from mozilla's `master` branch: 20 | ``` 21 | $ git checkout master -b mybranch 22 | ``` 23 | 24 | 2. While working, rebase your branch forwards regularly against the (daily) updates to `master`: 25 | ``` 26 | $ git checkout mybranch 27 | $ git fetch upstream 28 | $ git rebase upstream/master 29 | ``` 30 | 31 | > Sometimes there are conflicts during rebasing. If rebasing will cause some of your commits to not 32 | > build or otherwise make less sense then don't do it (`git rebase --abort`). 33 | > Instead finish the work on the current branch and submit the pull request without merging or rebasing. 34 | > Do not repeatedly merge `master` into your branch. We will ask you to rewrite any pull request that 35 | > contains unnecessary merge nodes. 36 | 37 | 3. When done, push your work up to github: 38 | ``` 39 | $ git push origin mybranch 40 | ``` 41 | 42 | 4. File a pull request against `rust-lang/rust`. Target the pull request to the `master` integration branch in `rust-lang/rust`. Once your pull request is filed, you can create a new branch and do something else. 43 | 44 | 5. Reviewers regularly look through the @bors integration queue, shown here: http://buildbot.rust-lang.org/bors/bors.html . Monitor your pull request for any additional comments or feedback from reviewers. Once an authorized reviewer leaves a comment on your pull request of the form `@bors: r+ ` (referring to the final commit in the pull request), @bors will attempt to merge your change to a temporary branch, test it, and advance `master` to that version if the tests pass. If any of these steps fail, it is your responsibility to address any problems that show up and refresh the pull request with updated code, so watch this process to ensure your change integrates. 45 | 46 | 6. Pull `master` into your local repo and verify that it contains your changes: 47 | ``` 48 | $ git checkout master 49 | $ git pull 50 | $ git log 51 | ... ... 52 | ``` 53 | 54 | 6. It is now safe to delete 'mybranch' from both local and remote repos: 55 | ``` 56 | $ git branch -D mybranch 57 | $ git push origin :mybranch 58 | ``` 59 | 60 | ## Git Submodules 61 | 62 | In order to create a git submodule, follow this procedure: 63 | 64 | 1. First we have to prepare the submodule. If the project is hosted on http://github.com, fork it so we can apply changes. Otherwise check it out and push it into http://github.com/rust-lang/ or wherever. 65 | 66 | 2. In the rust repository, create the submodule. Make sure that you specify a publicly accessible read-only url here, or else you may break the build for a non-rust developer: 67 | 68 | ``` 69 | $ git submodule add https://github.com/rust-lang/libuv.git src/rt/libuv 70 | ``` 71 | 72 | 3. Git will checkout the project into the subdirectory `src/rt/libuv`. We'll need to switch the origin to a writable repository so we can push to it. 73 | 74 | ``` 75 | $ cd src/rt/libuv 76 | $ git remote set-url origin git@github.com:rust-lang/libuv.git 77 | ``` 78 | 79 | 4. I would suggest creating a branch to track the remote project, which we'll use to designate which revision we'll pin rust to. We'll also use this branch to track any rust customizations: 80 | 81 | ``` 82 | cd src/rt/libuv 83 | $ git checkout -b rust ee599ec1141cc48f895de1f9d148033babdf9c2a 84 | # make some changes to the submodule... 85 | $ git push origin rust:refs/heads/rust 86 | ``` 87 | 88 | 5. Finally, commit the submodule to rust. git should have automatically added/modified `.gitmodules` and `src/rt/libuv`: 89 | 90 | ``` 91 | $ git status 92 | ... 93 | # Changes to be committed: 94 | # (use "git reset HEAD ..." to unstage) 95 | # 96 | # modified: .gitmodules 97 | # new file: foobar 98 | ... 99 | $ git commit -a 100 | ``` 101 | 102 | 6. To be safe, check to make sure you can clone and build rust from the read-only repository: 103 | 104 | ``` 105 | $ git clone --recursive https://github.com/rust-lang/rust.git 106 | $ configure 107 | $ make 108 | ``` 109 | 110 | ## Updating a submodule 111 | 112 | 1. Make your changes to the submodule and commit them to the rust branch. Check `git status` to make sure there are not unknown files. If there are, this can confuse the supermodule into thinking that you still have uncommitted changes in the submodule. So if you do, either commit those files or add them to either the `.gitignore` or `.git/info/exclude` file. 113 | 114 | ``` 115 | $ cd src/rt/libuv 116 | $ git checkout rust 117 | # Make your changes... 118 | $ git commit 119 | $ git status 120 | # On branch master 121 | # Untracked files: 122 | # (use "git add ..." to include in what will be committed) 123 | # 124 | # foo 125 | nothing added to commit but untracked files present (use "git add" to track) 126 | $ echo foo >> .gitignore 127 | $ git add .gitignore 128 | $ git commit 129 | ``` 130 | 131 | 3. Commit the submodule changes into the supermodule. 132 | 133 | ``` 134 | $ cd $rustdir 135 | $ git commit 136 | ``` -------------------------------------------------------------------------------- /Note-compiler-snapshots.md: -------------------------------------------------------------------------------- 1 | The compiler (`rustc`) is self-hosting. This means that while you develop, you "start" from a pre-built binary we serve from an archive server, and build new copies of the same program (from the same source) in your workspace. 2 | 3 | Self-hosting involves "stages". There are 4 stages to know about: 4 | 5 | * `stage0` is the stage you fetched from a snapshot server. The binaries in here correspond to versions from "recently" that were built on one of our development machines and uploaded to our archive server. The build system will download the snapshots into your workspace when building, in order to get you started, and pick up new snapshots as we make them. 6 | 7 | * `stage1` is your workspace compiled with `stage0`. It will contain any changes you made, but it will not yet have been *built with* those changes. It was built with a snapshot compiler. 8 | 9 | * `stage2` is your workspace compiled with `stage1`. It was built with your changes. 10 | 11 | * `stage3` is your workspace compiled with `stage2`; it should equal stage2, and is built only as a check to ensure that your change "converges" to a fixpoint where multiple compilations of self will result in the same binary image. 12 | 13 | The stage0 snapshots originated from a bootstrap compiler that has since been retired. We're running on all snapshots now. 14 | 15 | Occasionally we will make new snapshots. This may happen just to get a performance or code-quality improvement that is present on trunk, or it may have to do with wanting to use a feature in the code that is present on trunk. In any case the snapshots may need updating. 16 | 17 | Snapshots are made on a self-serve basis by users with write access to the repository. 18 | 19 | # Procedures 20 | 21 | All snapshots should be possible in a "self-serve" fashion now, for users with direct write access to the development repo. Follow the instructions below. Unfortunately they're still a bit heavy on manual work by the user, but the upside is you can learn to do it all yourself, without relying on anyone else being online. We'll make this more automatic as time goes by. 22 | 23 | If you have _any questions_ about these procedures, please drop by IRC and ask in person, and/or send mail to the mailing list asking for help. You can make a bit of a mess if you make a mistake during migration, so it's best to be sure what you're doing. 24 | 25 | ## READ THIS PART 26 | 27 | While you're making snapshots, you'll be pushing to non-`master` branches until your work is done and you need to integrate it back to `master`. [[Bors|Note-bors-usage]] or other people may be pushing to `master` in the meantime. It is essential that you _never_ rebase your snapshot-making commits when finishing your work and pushing to `master`. Use `git merge` if anyone else races with you in the meantime. Snapshots are identified by revision ID and those will change if you rebase. To avoid confusion, in general you should only create snapshots from commits that are already on master. 28 | 29 | You should probably also not race with other users who are themselves making snapshots; in theory it will work but only if the buildbots don't overlook your pushes. Since the buildbots are inexact (they just pull "the most recent change on a branch") it's possible no snapshot will get built for you, which will be sad. 30 | 31 | ## Stage3 snapshots 32 | 33 | * Push the commit you want to snapshot to the `snap-stage3` branch. You do this using the `local:remote` convention in git, pushing _your_ `master` branch to _Mozilla's_ `snap-stage3` branch. Assuming you have a remote configured for mozilla, that is, you run: 34 | ``` 35 | $ git push -f mozilla master:snap-stage3 36 | ``` 37 | 38 | * Wait for the [buildbots](http://buildbot.rust-lang.org/builders) to cycle. They will get around to building your commit. All of the `snap-X` builders will need to build green before the snapshot can be completed. 39 | 40 | * Open the build results of each of the snapshot builders. Do this by clicking on the most recent build number for each snapshot builder. Each builder logs a number of build steps and will have one or more lines that read something like 41 | 42 | ``` 43 | uploading rust-stage0-2013-07-29-63c9b11-freebsd-x86_64-e2aa76ac1d3edd5385cb572b47f34ecfa8c611d1.tar.bz2 44 | ``` 45 | 46 | * Open the `src/snapshots.txt` file and make a new 'S' entry at the _top_ of the file. It should look something like this: 47 | 48 | ``` 49 | S 2011-05-13 0d32ff7 50 | linux-i386 4adfe572211e609bf8faeb327ffabc4bb6bc3a1e 51 | macos-i386 bc7ee4d146ef6e0236afbd7cc4a9241582fd2952 52 | winnt-i386 5d3279a2dd0e3179b0e982432d63d79f87cac221 53 | ``` 54 | 55 | These are examples; you should use the values from the lines you pulled out of the logs. The thing to notice is that the first part `S 2011-05-13 0d32ff7` names the git revision you pushed, and the subsequent 3 indented lines name the per-platform snapshots and give their sha1 values, that you pulled out of the builder logs. Be sure to actually add the same number of lines as were included in the previous snapshot, otherwise you'll be leaving some platform out in the cold. That's not cool. 56 | 57 | * Save `src/snapshots.txt` and make check in your workspace. Make sure everything's cool. You are now building with your new snapshot locally. 58 | 59 | * Do a build locally, push to your branch and open a normal pull request. Bors will integrate it and then everybody will be using your snapshot. 60 | 61 | ## Local snapshots 62 | 63 | Sometimes you will want to make a snapshot just on your machine for testing. Executing ```make snap-stage3``` in your Rust build directory should leave behind a ```.bz2``` file. To rebuild Rust with the new snapshot, execute: 64 | 65 | ``` 66 | CFG_SRC_DIR=$HOME/rust ../src/etc/get-snapshot.py x86_64-apple-darwin \ 67 | rust-stage0-2012-11-03-444a16a-macos-x86_64-ed4b8355bfb1bcea6216bac585053a67e05df8a2.tar.bz2 68 | ``` 69 | 70 | modifying the value of ```CFG_SRC_DIR``` appropriately; using the correct host triple for your machine; and substituting whatever the name of the ```.bz2``` file that was just created. This will unzip the new snapshot and install it. Then you can run ```make check``` as normal. -------------------------------------------------------------------------------- /Docs.md: -------------------------------------------------------------------------------- 1 | Rust's primary documentation, including the tutorial, guides and manual, are on the Rust website. The wiki is mostly used for in-progress documentation or somewhat random pieces of advice/hints, as well as fast-evolving community maintained lists. 2 | 3 | * [Master](http://doc.rust-lang.org/master/index.html) - documentation for the 'master' branch of the git repository. 4 | * [Release 1.0.0-alpha.2](http://doc.rust-lang.org/1.0.0-alpha.2/index.html) - documentation for the latest release. 5 | 6 | Additional supplementary documentation is maintained here on the wiki. 7 | 8 | ## Tutorials/intros 9 | [[Rust for C++ programmers|Rust for CXX programmers]] - A cheat sheet 10 | [Rust for Rubyists](http://www.rustforrubyists.com/) - Excellent introduction to Rust 11 | [Rust by Example](http://rustbyexample.com/) - Comprehensive examples 12 | [[Teaching Rust]] 13 | [[More examples|Doc examples]] - Where to look for examples of Rust 14 | [[Rusticon|The Rusticon]] - A glossary of terms commonly used in Rust and Rust tools. 15 | 16 | ## Other documentation 17 | 18 | [[Releases|Doc releases]] - Links to current and old releases and documentation 19 | [[Detailed release notes|Doc detailed release notes]] - Further explanation of language changes 20 | [[Community libraries]] - A curated list of external libraries for Rust 21 | [The Periodic Table of Rust Types](http://cosmic.mearie.org/2014/01/periodic-table-of-rust-types) 22 | [[Computer Graphics and Game Development]] - Libraries and example projects 23 | [UVA Rust tutorial](http://aml3.github.io/RustTutorial/) 24 | 25 | ## Tools 26 | 27 | [[Packages, editors, and other tools|Doc packages, editors, and other tools]] 28 | [[Continuous integration|Doc continuous integration]] - Test your GitHub-hosted packages with Travis CI 29 | 30 | ## Platforms 31 | getting Rust working on other platforms 32 | 33 | [[Building for Android|Doc building for Android]] 34 | [[Building for iOS|Doc building for iOS]] 35 | [Cross-build for ARM Cortex M3/M4](https://github.com/hackndev/zinc) - Zinc bare metal stack 36 | 37 | ## Guides in other languages 38 | [Présentation du langage Rust](http://lea-linux.org/documentations/Rust) - Detailed documentation in French, with examples 39 | 40 | 41 | ## Community 42 | 43 | * IRC: 44 | 45 | *Note that to guard against botnet attacks we occasionally turn on moderation, disallowing 46 | 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.* 47 | 48 | * [#rust on irc.mozilla.org][pound-rust] - Main Rust channel - general discussion 49 | * [#rust-internals on irc.mozilla.org][pound-rust-internals] - Rust compiler and library development 50 | * [#rust-gamedev on irc.mozilla.org][pound-rust-gamedev] - game development in Rust 51 | * [#rust-osdev on irc.mozilla.org][pound-rust-osdev] - OS development in Rust 52 | * [#rust on irc.ozinger.org][pound-rust-korea] - Korean Rust community 53 | * Mailing list [rust-dev] 54 | * Reddit's [r/rust] 55 | * [Stack Overflow] 56 | * User groups 57 | * [Rust Bay Area][rust-bay-area] 58 | * [Rust Korea][rust-korea] 59 | * [Rust Skåne][rust-skane] 60 | * [Rust Samurai 其ノ壱](http://atnd.org/events/39890) 61 | * [Rust 中文社区][rust-zh] (on Google+) 62 | * [Rust London User Group][rust-london] 63 | * [Rust China](http://rust.cc/) 64 | * [Friends of the Tree][fott] - The Rust Team occasionally likes to recognize people for outstanding contributions to the Rust project, its ecosystem, and its community 65 | 66 | [pound-rust]: http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust 67 | [pound-rust-internals]: http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-internals 68 | [pound-rust-gamedev]: http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-gamedev 69 | [pound-rust-osdev]: http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-osdev 70 | [pound-rust-korea]: http://chat.mibbit.com/?server=irc.ozinger.org&channel=%23rust 71 | [rust-dev]: https://mail.mozilla.org/listinfo/rust-dev 72 | [r/rust]: http://reddit.com/r/rust 73 | [Stack Overflow]: http://stackoverflow.com/questions/tagged/rust 74 | [rust-bay-area]: http://www.meetup.com/Rust-Bay-Area/ 75 | [rust-korea]: http://rust-kr.org/ 76 | [rust-skane]: http://www.meetup.com/rust-skane/ 77 | [rust-zh]: https://plus.google.com/communities/100629002107624231185/ 78 | [rust-london]: http://www.meetup.com/Rust-London-User-Group/ 79 | [fott]: https://github.com/rust-lang/rust/wiki/Doc-friends-of-the-tree 80 | 81 | ## Presentations 82 | 83 | There is a steady stream of broadcast presentations on [Air Mozilla](https://air.mozilla.org/?tag=rust). 84 | 85 | Here are some collected presentations for other locations: 86 | 87 | * [ML Family Workshop 2014: The Rust Language and Type System (demo)](https://www.youtube.com/watch?v=RvbkD5nRGA8) - Felix Klock 88 | * [Panel: Systems Programming in 2014 and Beyond](http://channel9.msdn.com/Events/Lang-NEXT/Lang-NEXT-2014/Panel-Systems-Programming-Languages-in-2014-and-Beyond) - Niko Matsakis, Andrei Alexandrescu, Rob Pike, Bjarne Stroustrup 89 | * [Rust: Safe Systems Programming with the Fun of FP](http://www.techtalkshub.com/rust-safe-systems-programming-fun-fp/) - Felix Klock, CodeMesh 2014 90 | * [Niko's linux.conf.au talk 2014](https://t.co/aaYgMqZprC) - Memory ownership and Lifetimes. January 10, 2014. 91 | * [John Clements, 10-minute talk (video)](http://www.youtube.com/watch?v=_KgXy7jnwhY) at SoCal PLS on Rust, Macros, and Hygiene. December 2013. 92 | * [Felix's Codemesh 2013 slides](http://pnkfelix.github.io/present-rust-codemesh2013/fklock-rust-codemesh2013.pdf) 93 | * Geoffroy Couprie's [Scala.IO 2013 slides](http://dev.unhandledexpression.com/slides/rust-scalaio/) 94 | * Steve's presentation at RuPy 2013 "Nobody Knows Rust." [slides](http://steveklabnik.github.io/nobody_knows_rust/#/), video to come soon 95 | * [Tim's presentation at OS Bridge 2013](http://opensourcebridge.org/sessions/970) - And [slides](http://opensourcebridge.org/wiki/2013/Rust%3A_A_Friendly_Introduction) 96 | * [Niko's presentation at Northeastern](http://smallcultfollowing.com/babysteps/blog/2013/07/18/rust-presentation-at-northeastern/) - Slides only 97 | * [Dave Herman's StrangeLoop 2012 talk](http://www.infoq.com/presentations/Rust) -------------------------------------------------------------------------------- /Note-priority-issue-criteria.md: -------------------------------------------------------------------------------- 1 | These are the criteria used for prioritizing issues. Issues meeting these criteria should be nominated for triage and are generally tagged with `P` tags on the issue tracker and eventually scheduled for major feature-based releases. These were formerly the criteria for 'maturity milestones'. 2 | 3 | ## Well-defined 4 | 5 | This milestone says nothing about the stability of the language; reaching it means that we have the _means to measure_ the stability of the language. Until we have passed this milestone, we cannot meaningfully describe the stability of the language. 6 | 7 | ### Language level 8 | 9 | for each production in the grammar, we have written down (not necessarily committed-to forever, but written down, in a clear way): 10 | 11 | - unambiguous syntax 12 | - expansion 13 | - attribute processing 14 | - resolution rules 15 | - borrow checking and type checking rules 16 | - static evaluation 17 | - what static items are created on success 18 | - what static combinations represent errors 19 | - dynamic semantics 20 | - what values are constructed at runtime and when 21 | - which actions represent failure or other types of error 22 | - code generation and link-time constraints and definitions 23 | - miscellaneous implementation requirements 24 | - miscellaneous implementation permissions / room for variability 25 | - miscellaneous implementation advice or notes 26 | - an example of the production 27 | 28 | In addition, we have (at least for the grammar and the executable example, if not the type rules) the ability to extract and check the current compiler against the spec. This means parsing using the grammar and compiling-and-running the example(s). 29 | 30 | ### Tool level 31 | 32 | For each tool in the language tool-suite, there exists: 33 | - a manual page 34 | - a mechanism for running an integration test on the tool 35 | 36 | ### Library level 37 | 38 | For each library under consideration (core, std, etc.), there exists: 39 | - A list of symbols (including types) that exist, or a way to get it 40 | - A mechanism for generating a per-symbol smoketest that confirms the existence of the symbol, type of the symbol, and (if static) the value of the symbol. This mechanism will eventually form the basis of (simple) backward-compatibility testing. 41 | 42 | ### Platform target level 43 | 44 | For each supported target, there exists: 45 | - Enough machinery to execute the testsuite and measure its success 46 | 47 | ## Backwards compatible 48 | 49 | This is a subjective milestone that says that, given the ability-to-measure achieved in the "well defined" milestone, we are comfortable making a long-term support commitment to downstream users (servo in particular) to keep the set of symbols, definitions and passing-tests from contracting. We may add-to, clarify or enhance them, and we may make a new branch that deletes them, but at least on _some_ long-term-supported branch, we will not delete them or cause the set to contract or change existing parts. 50 | 51 | This still leaves some leeway for "fixing bugs" in existing definitions and judgment calls made on whether a change represents a "bug fix" or a "breaking change". 52 | 53 | ## Feature complete 54 | 55 | 56 | 57 | The purpose of this milestone is to measure the sense of "nothing missing" in the standard libraries, tool suite, target coverage and language semantics. That is, for anything reasonable that someone would want to do with a first-major-revision language, there's some reasonable way to do it with this language. 58 | 59 | This milestone is reached when we would be comfortable potentially deferring all subsequent additions to APIs, tool options and behavior and language features on the stable branch, and only doing fixes and performance work. 60 | 61 | ("Potentially" used here because it's reasonable to backport or land any backward compatible features into the stable branch; this milestone is merely a marker of not needing any of those features on a stable branch for it to be useful in production) 62 | 63 | This milestone also does not say anything about performance or fault levels. 64 | 65 | ## Well-covered 66 | 67 | This milestone denotes a stronger set of measurement mechanisms than the "well defined" milestone, though it's similar in spirit: it means we have sufficient mechanisms to measure the _detailed_ correctness and performance of the language and libraries, not just the rough-cut versions. 68 | 69 | it does not, as usual, define the actual correctness or performance targets themselves. Merely the ability-to-measure. 70 | 71 | ### Language level 72 | 73 | For each grammar production, and for each specification-paragraph in the grammar production, there is a test in the testsuite that checks conformance, or a documented decision that testing that paragraph is not possible or desirable. 74 | 75 | Since these tests are more extensive (and less-illustrative) than "example" code in the documentation, they should be out-of-line from the spec. 76 | 77 | ### Library level 78 | 79 | For each listed public API symbol, there exists: 80 | 81 | - documentation of the symbol 82 | - an execution unit test that meaningfully tests the symbol's documentation, or a decision that testing the documentation is not possible or desirable 83 | - possibly: measurement of line-coverage or path-coverage to a chosen level 84 | - possibly: a unit benchmark or a documented decision that the symbol is not possible or desirable to benchmark 85 | 86 | ### Tool level 87 | 88 | For each tool, there is an integration test for each tool/option combination in the manual page that confirms the end-to-end operation of the tool as documented, or a documented decision that testing is either not possible or undesirable. 89 | 90 | ## Production ready 91 | 92 | 93 | 94 | The purpose of this milestone is to represent a high degree of confidence the language's suitability for industrial use due to a high level of measured correctness and performance in the tests. 95 | 96 | In other words, for each of the aspects described in the "well covered" milestone, and for each supported target platform, test success and benchmark performance has reached a level deemed suitable for production use in environments with substantial business consequences for major defects or low performance. Where possible, performance benchmarks are linked to equivalent benchmarks in competitive languages, and rust is sufficiently close to equivalent in performance. 97 | -------------------------------------------------------------------------------- /Lib-simd.rest: -------------------------------------------------------------------------------- 1 | SIMD for Rust 2 | ============= 3 | 4 | Discussion 5 | ---------- 6 | 7 | Rust `issue 3499`_. 8 | 9 | .. _issue 3499: https://github.com/mozilla/rust/issues/3499 10 | 11 | Standards 12 | --------- 13 | 14 | A vector type is defined by the element type and the number of elements. 15 | 16 | Rust recognizes 10 `machine types`_: ``i8``, ``i16``, ``i32``, ``i64``, 17 | ``u8``, ``u16``, ``u32``, ``u64``, ``f32``, ``f64``. 18 | 19 | .. _machine types: http://static.rust-lang.org/doc/master/rust.html#machine-types 20 | 21 | OpenCL_ defines Built-in Vector Data Types intended to be compiled to SIMD. 22 | Possible element types are ``char``, ``short``, ``int``, ``long``, 23 | ``uchar``, ``ushort``, ``uint``, ``ulong``, ``float``, ``double``, 24 | which maps one to one to Rust machine types. 25 | Possible number of elements are 2, 3, 4, 8, 16. 26 | 3-elements vector types were introduced in OpenCL 1.1. 27 | All possible combinations of element types and number of elements are 28 | defined. While OpenCL defines ``bool`` and ``half`` scalar types, 29 | they are not allowed as element types of vector types at the moment, 30 | although they are reserved for future extensions. 31 | 32 | .. _OpenCL: http://www.khronos.org/registry/cl/ 33 | 34 | LLVM has a `vector type`_ intended to be compiled to SIMD. 35 | All integers and floating point types can be element types. Apart from 36 | Rust's 10 machine types, these include ``i1`` and ``half``. 37 | There is no restriction on number of elements. 38 | 39 | .. _vector type: http://llvm.org/docs/LangRef.html#vector-type 40 | 41 | `Intel Software Developer's Manual`_ (Order Number 253665) provide 42 | information about SSE SIMD. 43 | 44 | .. _Intel Software Developer's Manual: http://www.intel.com/content/www/us/en/processors/architectures-software-developer-manuals.html 45 | 46 | According to Software Developer's Manual section Packed SIMD Data Types, 47 | there are 64-bit and 128-bit vector types. (It is missing in the section, 48 | but AVX also defines 256-bit vector types.) 64-bit vectors can be 49 | 8 packed byte integers, 4 packed word integers, 2 packed doubleword integers. 50 | (No floating-point values are available for 64-bit vectors.) 128-bit vectors 51 | can be 16 packed byte integers, 8 packed word integers, 4 packed doubleword 52 | integers, 2 packed quadword integers, 4 packed single precision 53 | floating point, 2 packed double precision floating point. Some integer 54 | operations are available in both signed and unsigned version, but some 55 | are not: for example, there is no unsigned integer comparison. 56 | 57 | ARM publications `RVCT Assembler Guide`_ (ARM DUI 0204) and 58 | `RVCT Compiler Reference Guide`_ (ARM DUI 0348) provide informations about 59 | NEON SIMD. 60 | 61 | .. _RVCT Assembler Guide: http://infocenter.arm.com/help/topic/com.arm.doc.dui0204j/ 62 | .. _RVCT Compiler Reference Guide: http://infocenter.arm.com/help/topic/com.arm.doc.dui0348c/ 63 | 64 | According to Assembler Guide section NEON and VFP data types, 65 | NEON data types are ``S8``, ``S16``, ``S32``, ``S64``, 66 | ``U8``, ``U16``, ``U32``, ``U64``, ``F16``, ``F32``, ``P8``, ``P16``. 67 | ``F64`` is not available and ``F16`` support is optional. 68 | ``P8`` and ``P16`` are polynomials over GF(2). 69 | Vector types need to be either 64 bits or 128 bits long. 70 | 71 | According to Compiler Reference Guide section Vector data types, 72 | these types are named like ``int8x8_t``, ``int8x16_t``, 73 | ``uint8x8_t``, ``uint8x16_t``, ``float32x2_t``, ``float32x4_t`` in C. 74 | The number of elements can be 1 in case of ``int64x1_t``. 75 | 76 | XXX Research AltiVec. 77 | 78 | Languages 79 | --------- 80 | 81 | SIMD architectures usually define C API(compiler intrinsics) in 82 | addition to instructions. C API is provided by headers such as 83 | ``emmintrin.h`` for SSE2, ``arm_neon.h`` for NEON, ``altivec.h`` for 84 | AltiVec. These APIs are architecture-specific, but common to all 85 | compilers. 86 | 87 | Compilers can also provide language extensions common to all 88 | architectures. GCC_ provides vector_size_ attribute, Clang_ provides 89 | ext_vector_type_ attribute. XXX Research MSVC. 90 | 91 | .. _GCC: http://gcc.gnu.org/ 92 | .. _vector_size: http://gcc.gnu.org/onlinedocs/gcc/Vector-Extensions.html 93 | .. _Clang: http://clang.llvm.org/ 94 | .. _ext_vector_type: http://clang.llvm.org/docs/LanguageExtensions.html#vectors-and-extended-vectors 95 | 96 | There is the issue of what to do when SIMD is not available. GCC 97 | provides indirect function, which can select optimized version 98 | at load time, using ifunc_ attribute. GCC 4.8 also introduced 99 | `function multiversioning`_ for C++, which uses the same mechanism. 100 | 101 | .. _ifunc: http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html 102 | .. _function multiversioning: http://gcc.gnu.org/wiki/FunctionMultiVersioning 103 | 104 | AMD developed SSEPlus_, which emulates newer SSE instructions on 105 | older architectures. The interface provided is the same as compiler 106 | intrinsics. 107 | 108 | .. _SSEPlus: http://sseplus.sourceforge.net/ 109 | 110 | Johann Wolfgang Goethe-Universität Frankfurt am Main's 111 | Department of High Performance Computer Architecture develops 112 | softwares to help analysis of experimental data from CERN. 113 | One such software is Vc_, a C++ library to help the use of SIMD. 114 | It defines C++ classes ``int_v``, ``uint_v``, ``float_v``, ``double_v``, 115 | which provides overloaded C++ operators. 116 | 117 | .. _Vc: http://code.compeng.uni-frankfurt.de/projects/vc 118 | 119 | Microsoft published XNAMath_ as part of DirectX SDK. XNAMath was later 120 | renamed to DirectXMath_ and published as part of Windows SDK. Since 121 | Windows 8 runs on both Intel and ARM architectures and Xbox 360 uses 122 | PowerPC, DirectXMath abstracts over SSE, NEON, AltiVec. 123 | 124 | .. _XNAMath: http://blogs.msdn.com/b/chuckw/archive/2010/01/29/a-little-love-for-xnamath.aspx 125 | .. _DirectXMath: http://blogs.msdn.com/b/chuckw/archive/2012/03/27/introducing-directxmath.aspx 126 | 127 | D has core.simd_. 128 | 129 | .. _core.simd: http://dlang.org/phobos/core_simd.html 130 | 131 | Mono provides Mono.Simd_. 132 | 133 | .. _Mono.Simd: http://docs.go-mono.com/?link=N:Mono.Simd 134 | 135 | `GHC SIMD`_ project. 136 | 137 | .. _GHC SIMD: http://hackage.haskell.org/trac/ghc/wiki/SIMD 138 | 139 | `Haskell Beats C Using Generalized Stream Fusion`_ paper. 140 | 141 | .. _Haskell Beats C Using Generalized Stream Fusion: http://research.microsoft.com/en-us/um/people/simonpj/papers/ndp/haskell-beats-C.pdf 142 | 143 | For Common Lisp, there are sb-simd_ and cl-simd_. 144 | 145 | .. _sb-simd: http://common-lisp.net/projects/sb-simd/ 146 | .. _cl-simd: https://github.com/angavrilov/cl-simd 147 | 148 | `Using SIMD in Dart`_. 149 | 150 | .. _Using SIMD in Dart: https://www.dartlang.org/articles/simd/ -------------------------------------------------------------------------------- /Note-0.5-priorities.md: -------------------------------------------------------------------------------- 1 | # Possible 0.5 priorities 2 | 3 | ### Complete traits to unblock development of standard libraries (nmatsakis) 4 | 5 | I personally think a good overarching goal for 0.5 would be to "unblock" the development of strong standard libraries. It is my opinion that the single biggest blocker here is our incomplete trait implementation. In particular: 6 | 7 | - there are bugs around explicit self, not all of which have issues associated with them; 8 | - default methods and trait inheritance don't really work; 9 | - we need a deriving-like solution for implementing repetitive traits like Eq, IterBytes, Serialize, and so forth; 10 | - some lingering decisions on precisely what kinds of impls will be allowed (I have an in-progress blog pending on this post...) to avoid theoretical quandries when resolving; 11 | - @Trait, &Trait, and ~Trait do not really work. 12 | 13 | Fixing those things, primarily the first three, strikes me as very high priority. It would allow us to define nice trait hierarchies similar to the ones found in Haskell/Clojure (Eq, Ord, Hash, etc) which form the foundation of a strong library design. 14 | 15 | ### Better treatment of extern fns (nmatsakis) 16 | 17 | This would eliminate the last use of modes, and obviously it's a common area that people interact with. 18 | 19 | https://github.com/mozilla/rust/issues/3678 20 | 21 | https://github.com/mozilla/rust/issues/2628 22 | 23 | ### Pattern bindings (nmatsakis) 24 | 25 | These are the last vestige of modes. Finish https://github.com/mozilla/rust/issues/3271 26 | 27 | ### Explicit self, freezable data structures (nmatsakis) 28 | 29 | I would like to move map over the freezable version. This requires using a trait with explicit self. There are some bugs that prevent this from working which I haven't fully written up yet. Probably more I haven't found yet. In general we should transition to making explicit self mandatory. 30 | 31 | ### Complete the fn type transition (nmatsakis) 32 | 33 | The fn types are a mess right now. They are unsound in various ways (#2829, #3696, perhaps others), you can't have a fully const-ified send-map, and we don't support one-shot closures (#2549). This should be rectified. 34 | 35 | ### Miscellaneous regions bugs (nmatsakis) 36 | 37 | There are various bugs in the region type system implementation. I will go through and collect some issue numbers later. They ought to be fixed. 38 | 39 | ### Condition-handler system (graydon) 40 | 41 | It's difficult to write libraries presently that have "recoverable" failure modes. We've long talked about a pattern for this using TLS. We gained TLS in 0.4. We should give this a try in 0.5, it'll help a lot in writing reasonable libraries. 42 | 43 | ### Start on new driver, build and command-line tooling (graydon, brson) 44 | 45 | Probably won't be time to finish this, but a new driver, as well as a maintainer-mode tool for bootstrapping the compiler and doing tasks currently done via 'make' (rather than using the makefile) should at least get started. Also probably involves adding a top-level `rust` command and renaming subtools a bit. 46 | 47 | Ideally Rust's build system will use cargo for dependency resolution and provide reusable components for others'. Servo has a complex build using awful makefiles that would be better managed by cargo or a cargo-based build tool. 48 | 49 | ### Performance work (graydon) 50 | 51 | The build time is a regular source of complaint during development, and it limits a lot of what we can get done in a day. We should spend some energy on speeding this cycle up and making sure everyone's able to build as quickly and in-parallel as possible. 52 | 53 | ### Build automation, code review and integration throughput (graydon) 54 | 55 | Switching our build system over to buildbot (now reviewed and in testing) will be good here. Bringing more and faster build slaves into production. And teaching the automation to do integration builds for us rather than bouncing off incoming. 56 | 57 | We should also experiment with some more-structured code review, as our velocity slows and we start focusing on quality and performance issues in this and subsequent releases. 58 | 59 | ### Remove obsolete features (brson) 60 | 61 | Including modes, export, structural Records, #-macros, [mut], assert/log/fail, <-, <->, []/_, fn& 62 | 63 | ### Upgrade and unblock uv on x86 (brson) 64 | 65 | Our uv build is very, very far behind upstream, and simply doesn't work on 32-bit x86 because of rustc bugs. 66 | 67 | ### Cargo improvement and continuous integration (brson) 68 | 69 | Cargo has some pretty nice capabilities but we haven't fully committed to it yet. Servo (and maybe Rust) should be using cargo to manage their dependencies and installation. I'm imagining this has a lot of overlap with the rewrite of Rust's build system. 70 | 71 | Keeping out-of-tree code up to date has become a very labor-intensive process, and our support for out-of-tree libraries is bad. I very much want to set up a continuous integration server for the entire community. Doing this completely in Rust helps uv, cargo, and servo, and is fun. 72 | 73 | ### Tree cleanup (brson) 74 | 75 | There are a few things I would like to do to clean up the build, including making all crates libraries so they can be used by other tools, fixing the weird organization of librustc and its driver, splitting rustllvm out into its own crate with bindings, ditto clang, refactoring the top-level rustc code so that it is more approachable to newcomers, merging rt and core, moving the native uv and compression code to std. 76 | 77 | ### All runtime tests passing under JIT (z0w0) 78 | 79 | The JIT compiler passes about 92% tests, give or take a few on different platforms (Windows hasn't even been tested). The failing tests are caused by segfaults, illegal instructions and the occasional task failure. Being able to have all Rust code running perfectly under JIT on all platforms would be an amazing feature of 0.5. 80 | 81 | ### Remove move/copy (brson) 82 | 83 | If we are going to do it, it needs to be sooner than later, as it is another disruptive change. 84 | 85 | http://smallcultfollowing.com/babysteps/blog/2012/10/01/moves-based-on-type/ 86 | 87 | ### Fix unwinding on Windows (brson) 88 | 89 | The most promising short-term solution (unwinding by propagating a return value) also helps fix our compile time performance. 90 | 91 | ### Replace core::comm with pipes (brson) 92 | 93 | Having two systems here is not good. 94 | 95 | ### Fix .rc/.rs/companion module issues (brson) 96 | 97 | Our implicit loading of .rs files is confusing 98 | 99 | ### Add labeled break and continue (brson) 100 | 101 | Henri still needs it for the HTML parser. 102 | 103 | ### Dependency generation (tjc) 104 | 105 | Add the ability to generate/view item dependencies, as a prequel to incremental compilation. 106 | 107 | ### Newtyped structs and struct variants (pcwalton) 108 | 109 | Newtyped structs and struct variants don't work. -------------------------------------------------------------------------------- /Note-tag-label-names-and-definitions.md: -------------------------------------------------------------------------------- 1 | The word "Issues" encompassed both bugs and feature requests. 2 | 3 | If the meaning is blank, then the meaning is implicit in the name 4 | (contribute a clarifying definition if you believe the meaning is not 5 | self-evident). 6 | 7 | If the meaning is a "?", then Felix did not immediately know the 8 | meaning of the label and does not think it is self-evident. 9 | 10 | | *TAGS LABELS* | Meaning | 11 | |:-------------------------|:--------------------------------------------------| 12 | | *AREA TAGS* | | 13 | | A-an-interesting-project | A self-contained independent project | 14 | | A-android | Related to Android mobile device OS | 15 | | A-attributes | Issues with Rust meta-data attributes | 16 | | A-build | Issues bootstrapping rust compiler and runtime | 17 | | A-codegen | Issues with rustc code generator | 18 | | A-concurrency | Scheduler, tasks, plus other concurrency idioms | 19 | | A-debuginfo | Debug meta-data for integration with `gdb` | 20 | | A-destructors | Destructors (static lifetime based; not [finalization][1]) | 21 | | A-diagnostics | Error reporting (some overlap with A-lint) | 22 | | A-docs | Issues with tutorials, manuals, and API docs | 23 | | A-driver | Issues with wrapper around rustc/rustdoc/etc | 24 | | A-ffi | Foreign Function Interface i.e. interop with C/C++| 25 | | A-freebsd | Related to FreeBSD operating system | 26 | | A-frontend | Issues with rustc frontend (`librustc::front::*`) | 27 | | A-grammar | Grammar spec (not *implementation*; see A-parser) | 28 | | A-iOS | Related to Apple iOS device operating system | 29 | | A-infrastructure | Mozilla-hosted services: buildbot, website, etc | 30 | | A-instrumentation | Rust library / object code instrumentation | 31 | | A-libs | Rust standard and contributed libraries | 32 | | A-linkage | Crate format+tooling for dynamic/static linking | 33 | | A-lint | Warning categorization and tooling in rustc | 34 | | A-linux | Related to Linux operating system | 35 | | A-llvm | Related to LLVM IR and code-generation library | 36 | | A-macos | Related to Apple Mac OS X operating system | 37 | | A-metadata | Crate-embedded data for reflection/compilation | 38 | | A-parser | Parser impl. (not *specification*; see A-grammar) | 39 | | A-pkg | Issues with package management e.g. rustpkg | 40 | | A-plugin | compiler plugins and their infrastructure | 41 | | A-pretty | Pretty-printing rust source via `rustc --pretty` | 42 | | A-regions | Lifetime semantics; borrow-checker (aka borrowck) | 43 | | A-resolve | Identifier/name resolution | 44 | | A-runtime | Task scheduler, memory management, core I/O | 45 | | A-rustdoc | API documentation extraction and generation tool | 46 | | A-rusti | rusti is a REPL-like dynamic Rust interpreter | 47 | | A-syntaxext | syntax extensions aka macros i.e. `macro_rules!` | 48 | | A-testsuite | | 49 | | A-tools | For Rust user: syntax highlighting, profiling, etc| 50 | | A-traits | Trait system provides bounded polymorphism + OOP | 51 | | A-typesystem | Rust's static type system, type check (aka typeck)| 52 | | A-unicode | Unicode handling, parsing or conversion | 53 | | A-versioning | Version numbers/handling for language + libraries | 54 | | A-visibility | Visibility/privacy: item pub/priv and their access| 55 | | A-windows | Related to Microsoft Windows operating system | 56 | |   | 57 | | *BLOCKER TAGS* | | 58 | | B-RFC | Blocked on a Request-for-Comment | 59 | | B-clarifying | put label description here | 60 | | B-reproduce | Blocked on a need to reproduce problem locally | 61 | |   | 62 | | *EFFORT TAGS* | | 63 | | E-easy | Effort: easy | 64 | | E-hard | Effort: hard | 65 | | E-mentor | ? | 66 | | E-needtest | Effort: requires a unit test to be closed | 67 | | E-tedious | Effort: tedious | 68 | |   | 69 | | *IMPACT TAGS* | | 70 | | I-ICE | Importance: error internal to rustc | 71 | | I-cleanup | Importance: Internal source code cleanup | 72 | | I-completion | Importance: fill gaps in existing implementation | 73 | | I-crash | Importance: Rust runtime/program is crashing | 74 | | I-enhancement | Importance: Potential tools/language enhancement | 75 | | I-nominated | Importance: Nominated for a milestone | 76 | | I-papercut | Importance: easily fixable usability bug | 77 | | I-slow | Importance: slow (in compile or running time) | 78 | | I-wishlist | Importance: would be nice but can do without | 79 | | I-wrong | Importance: behavior does not match specification | 80 | |   | 81 | | *PRIORITY TAGS* | | 82 | | P-backcompat-lang | Priority: Language backward-compatible | 83 | | P-backcompat-lib | Priority: Library backward-compatible | 84 | | P-high | Priority: High | 85 | | P-low | Priority: Low | 86 | |   | 87 | | *uncategorized tags* | | 88 | | metabug | Collects several related issues together | 89 | 90 | [1]: http://en.wikipedia.org/wiki/Finalizer 91 | -------------------------------------------------------------------------------- /Lib-io.md: -------------------------------------------------------------------------------- 1 | Module editing plan template 2 | 3 | ## 1. Announcement to mailing list 4 | 5 | - Proposed editor: _your name_ 6 | - Date proposed: _date of proposal_ 7 | - Link: _link to email_ 8 | 9 | ### Notes from discussion on mailing list 10 | 11 | - [WIP](https://github.com/brson/rust/tree/io/src/libcore/rt/io) 12 | - [API sketch](https://gist.github.com/brson/5399629) 13 | 14 | ## 2. Research of standards and techniques 15 | 16 | 1. Standard: _standard_ 17 | - _link to docs_ 18 | - ... 19 | 20 | ### Summary of research on standards and leading techniques 21 | #### Relevant standards and techniques exist? 22 | #### Those intended to follow (and why) 23 | #### Those intended to ignore (and why) 24 | 25 | ## 3. Research of libraries from other languages 26 | 27 | - [.NET](http://msdn.microsoft.com/en-us/library/system.io%28v=vs.71%29.aspx) 28 | - Java [io](http://docs.oracle.com/javase/6/docs/api/java/io/package-summary.html) [nio](http://docs.oracle.com/javase/6/docs/api/java/nio/package-summary.html) 29 | - [C / C++ stdio](http://www.cplusplus.com/reference/cstdio/) 30 | - [C++ iostreams](http://www.cplusplus.com/reference/iostream/) - Probably don't want to take a lot of influence from C++ 31 | - [C++ boost iostreams](http://www.boost.org/doc/libs/1_53_0/libs/iostreams/doc/index.html) 32 | - [C (Plan 9) bio](http://swtch.com/usr/local/plan9/include/bio.h) [man](http://man.cat-v.org/plan_9/2/bio) - tidied up / simplified stdio 33 | - [D stdio](http://dlang.org/phobos/std_stdio.html) - stdio-like 34 | - [Go](http://golang.org/pkg/io/) - many fine-grained interfaces 35 | - [bufio](http://golang.org/pkg/bufio/) for buffered I/O 36 | - [io](http://golang.org/pkg/io/) 37 | - interface `ByteReader`: `ReadByte()` 38 | - interface `ByteScanner`: interface `ByteReader` + `UnreadByte()` 39 | - interface `ByteWriter`: `WriteByte()` 40 | - interface `Closer`: `Close()` 41 | - interface `ReadCloser`: interfaces `Reader` + `Closer` 42 | - interface `ReadSeeker`: interfaces `Reader` + `Seeker` 43 | - interface `ReadWriteCloser`: interfaces `Reader` + `Writer` + `Closer` 44 | - interface `ReadWriteSeeker`: interfaces `Reader` + `Writer` + `Seeker` 45 | - interface `ReadWriter`: interfaces `Reader` + `Writer` 46 | - interface `Reader`: `Read()` 47 | - interface `ReaderAt`: `ReadAt()` 48 | - interface `ReaderFrom`: `ReadFrom()` 49 | - interface `RuneReader`: `ReadRune()` 50 | - interface `RuneScanner`: interface `RuneReader` + `UnreadRune()` 51 | - interface `Seeker`: `Seek()` 52 | - interface `WriteCloser`: interfaces `Writer` + `Closer` 53 | - interface `WriteSeeker`: interfaces `Writer` + `Seeker` 54 | - interface `Writer`: `Write()` 55 | - interface `WriterAt`: `WriteAt()` 56 | - interface `WriterTo`: `WriteTo()` 57 | - [io.util](http://golang.org/pkg/io/ioutil/) 58 | - `ReadAll` reads from r until an error or EOF and returns the data it read. 59 | - [Python 3 io](http://docs.python.org/3.2/library/io.html) - includes text/binary division 60 | - [Common Lisp streams](http://www.lispworks.com/documentation/HyperSpec/Body/c_stream.htm) - very composable, possibly over-engineered 61 | - [Haskell System.IO](http://www.haskell.org/ghc/docs/latest/html/libraries/base-4.6.0.1/System-IO.html) 62 | - Ada [streams](http://www.ada-auth.org/standards/12rm/html/RM-13-13-1.html) [streamIO](http://www.ada-auth.org/standards/12rm/html/RM-A-12-1.html) [sequentialIO](http://www.ada-auth.org/standards/12rm/html/RM-A-8-1.html) 63 | - Lua [LTN12: filters sources and sinks](http://lua-users.org/wiki/FiltersSourcesAndSinks) as used in [LuaSocket](http://w3.impa.br/~diego/software/luasocket/ltn12.html) 64 | 65 | ### Code examples 66 | 67 | * http://pleac.sourceforge.net/ 68 | * [Ruby tutorial](http://ruby.bastardsbook.com/chapters/io/) 69 | 70 | ### Summary of research from other languages: 71 | #### Structures and functions commonly appearing 72 | 73 | ##### Types of I/O sources and sinks 74 | 75 | - File 76 | - TCP socket 77 | - Unix domain socket 78 | - Pipe 79 | - UDP 80 | - Memory buffer 81 | - String 82 | - Formatting + formatted values 83 | - Serialization 84 | 85 | ##### IO adaptors / filters / converters 86 | 87 | - Pattern matching and replacement 88 | - Character encodings 89 | - Compression 90 | - Encryption 91 | 92 | #### Variations on implementation seen 93 | 94 | ##### Error handling 95 | 96 | * Return values - requires explicit checks, lots of noise 97 | * Exceptions - results in nicer looking code, error handling at arbitrary granularity 98 | 99 | #### Pitfalls and hazards associated with each variant 100 | #### Relationship to other libraries and/or abstract interfaces 101 | 102 | ## 4. Module writing 103 | 104 | - Pull request: _link to bug_ 105 | 106 | ### Additional implementation notes 107 | 108 | #### Error handling 109 | 110 | I/O is an area where nearly every operation can result in unexpected errors. It needs to be convenient to use I/O on the non-error path while also possible to handle errors efficiently. 111 | 112 | Some use cases: 113 | * I'm hacking together a quick prototype or script that does a bunch of file manipulation. Thinking about all the possible ways I/O could fail is not the point of this work and it's ok for the entire process to fail if something goes wrong. I don't want to be inconvenienced with handling errors. 114 | * I'm doing some performance critical I/O on a server and want to recover from an I/O failure in the most efficient way possible. I'm ok with writing extra error handling code. 115 | 116 | In Rust our error handling options are 'conditions' and the `Result` type. 117 | 118 | Conditions are events that can be raised, usually upon error, and optionally handled by dynamically-scoped 'condition handlers'. An unhandled condition results in task failure. Condition handlers are not like exceptions - they are handled at the site of the error, not after unwinding the stack. There is no way in Rust to 'catch' an exception. Conditions are not used widely and it's unknown how well they work in practice. 119 | 120 | The `Result` type is a monad-like type that can either be `Ok(A)` or `Err(B)`. Calculations on `Result` can be chained together in various ways based on previous results. They are generally considered unwieldy. 121 | 122 | ##### A proposed error handling strategy 123 | 124 | The I/O library will use a combination of conditions and fallable (Result, Option) or otherwise 'nullable' values (explained in detail later). 125 | 126 | All I/O errors will raise a condition and so will, by default, trigger task failure. This removes most of the obligation for the programmer to think about error handling on the successful path. 127 | 128 | When a condition is handled I/O libraries will essentially be expected to turn the current operation into a no-op, possibly returning a sensible null or error value, as appropriate each specific function. This behavior of always being able to return *some* value on error will allow errors to be recovered without creating new tasks, which is seen as expensive, and also problematic when managed data is involved. 129 | 130 | TODO 131 | 132 | #### Reader/Writer composition 133 | 134 | TODO 135 | 136 | #### Questions 137 | 138 | * Is ReaderUtil/WriterUtil the proper abstraction? 139 | * Do we need to consider string/character readers more carefully than mixins on Readers and Writers? For example, there are multiple options for handling newlines, and the ReaderUtil/WriterUtil trait doesn't have the state to store a flag. 140 | * Need to think about iteration, `each_byte` etc. and how it relates to iteration elsewhere. 141 | * How to avoid allocating strings/vectors unnecessarily? e.g. string/character readers should slice into the string/vector instead of constructing an entirely new string to read a line, but a file reader will need to allocate a vector/string to read a line. If the API is going to be same between such readers, then the functions return (or, call callbacks with) either `&str` or `~str`. For `&str`, a function that wants a `~str` will have to allocate (a second time, for a file reader); for `~str`, the string reader will always have to allocate even though many callbacks only need a `&str`. (Possible solution: use a trait that allows strings to be converted to the other types of strings which only allocates when necessary, i.e. just returns the original string for `~str` -> `~str`.) -------------------------------------------------------------------------------- /Lib-rand.md: -------------------------------------------------------------------------------- 1 | Generating random numbers, and sampling from random distributions. 2 | 3 | ## 1. Announcement to mailing list 4 | 5 | - Proposed editor: Huon Wilson ([@huonw](https://github.com/huonw)) 6 | - Date proposed: _date of proposal_ 7 | - Link: _link to email_ 8 | 9 | ### Notes from discussion on mailing list 10 | 11 | - [first discussion](https://mail.mozilla.org/pipermail/rust-dev/2013-April/003843.html) 12 | 13 | ## 2. Research of standards and techniques 14 | 15 | 1. Standard: _standard_ 16 | - _link to docs_ 17 | - ... 18 | 2. Standard: _standard_ 19 | - _link to docs_ 20 | - ... 21 | 1. Technique: Generating random bits/numbers (i.e `u32` or `u64`) 22 | - http://en.wikipedia.org/wiki/List_of_random_number_generators 23 | - http://en.wikipedia.org/wiki/Cryptographically_secure_pseudorandom_number_generator 24 | - [ISAAC/ISAAC-64 RNG](http://en.wikipedia.org/wiki/ISAAC_%28cipher%29) 25 | - cryptographically secure 26 | - http://burtleburtle.net/bob/rand/isaacafa.html 27 | - ISAAC is the main RNG used in rust at the moment 28 | - I've found little/no information about ISAAC-64 29 | - ["On the pseudo-random generator ISAAC" Aumasson 2006](http://eprint.iacr.org/2006/438.pdf) (details some problems in ISAAC and proposes a slight improvement ISAAC+) 30 | - [Mersenne Twister](http://en.wikipedia.org/wiki/Mersenne_twister) 31 | - "The Mersenne twister is the default random number generator for Python,[7][8] Ruby,[9] R,[10] PHP,[11] MATLAB and also available in C++[12] since C++11." 32 | - "The algorithm in its native form is not suitable for cryptography" 33 | - [SIMD-oriented Fast Mersenne Twister (SFMT)](http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/SFMT/) 34 | - dSFMT is used by Julia, and possibly Erlang 35 | - A fairly straight translation of the C of the 32 and 64 bit variants of MT19937 appears to be ~10% slower than ISAAC and ISAAC-64 respectively ([benchmarks here](https://github.com/mozilla/rust/pull/10029#issuecomment-26983157)) 36 | - [Xorshift](http://en.wikipedia.org/wiki/Xorshift) 37 | - Not crypto quality, but simple, small and fast 38 | - Currently the only other RNG in Rust 39 | - ["On the Xorshift Random Number Generators" Panneton & L'Ecuyer 2005(?)](http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.63.7497&rep=rep1&type=pdf) (analysis of and improvements to the xorshift generators) 40 | - [LFSR](http://en.wikipedia.org/wiki/Linear_feedback_shift_registers), aka Tausworthe generators 41 | - Not crypto quality, fast 42 | - ["Tables of maximally equidistributed combined LSFR generators" L'Ecuyer 1999](http://www.ams.org/mcom/1999-68-225/S0025-5718-99-01039-X/S0025-5718-99-01039-X.pdf) (includes a 64 bit variant) 43 | - ["Maximally Equidistributed Combined Tausworthe Generators" L'Ecuyer 1996](http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.43.4155) 44 | - ["Random Numbers Generated by Linear Recurrence Modulo Two" Tausworthe 1965](http://www.ams.org/journals/mcom/1965-19-090/S0025-5718-1965-0184406-1/S0025-5718-1965-0184406-1.pdf) 45 | - [WELL](http://en.wikipedia.org/wiki/Well_Equidistributed_Long-period_Linear) 46 | - Better randomness properties than Mersenne twister 47 | - Fairly fast public domain implementation on p8 of http://www.lomont.org/Math/Papers/2008/Lomont_PRNG_2008.pdf (this is an overview of multiple RNG algorithms) 48 | - [MWC/CMWC](http://en.wikipedia.org/wiki/Multiply-with-carry) 49 | - Not crypto quality, fast 50 | - ["Random Number Generators" Marsaglia 2003](http://www.jmasm.com/journal/2003_vol2_no1.pdf) (pages 6-17, also relevant to xorshift) 51 | - Wichmann Hill 52 | - ["Generating good pseudo-random numbers" Wichmann-Hill 2005](http://dl.acm.org/citation.cfm?id=1219278) 53 | - Hardware 54 | - `RDRAND` on Ivy Bridge x64 CPUs ([example of use in a Haskell package](https://github.com/TomMD/entropy/blob/master/cbits/rdrand.c)) 55 | - Assorted names: YARN5, Lagged Fibonacci, Multiple recurrence 56 | 57 | 2. Technique: Testing quality of random numbers 58 | - Very important! Extremely hard to tell if random numbers are "random enough" (a bug in an implementation, or a bad algorithm, can produce numbers that look random but aren't random enough for many purposes). 59 | - [Overview wikipedia article](http://en.wikipedia.org/wiki/Randomness_test) 60 | - [Diehard tests](http://en.wikipedia.org/wiki/Diehard_tests) (e.g. [dieharder](http://www.phy.duke.edu/~rgb/General/dieharder.php)) 61 | - [TestU01](http://en.wikipedia.org/wiki/TestU01) including "Small crush", "Crush" and "Big crush" 62 | - [tests written by the creator of ISAAC](http://burtleburtle.net/bob/rand/testsfor.html) 63 | - [ENT](http://www.fourmilab.ch/random/) 64 | - [NIST](http://csrc.nist.gov/groups/ST/toolkit/rng/index.html) 65 | - Add a new make target "check-rngs" with a testsuite? 66 | 3. Technique: sampling from distributions 67 | - Converting ints to floats: 68 | - Most languages/implementations just multiply the random int by `2**-num_bits` to get a float in `[0,1)`. 69 | - ["Conversion of High-Period Random Numbers to Floating Point" Doornik 2006](http://www.doornik.com/research/randomdouble.pdf) 70 | - General: 71 | - [Inverse transform sampling](http://en.wikipedia.org/wiki/Inverse_transform_sampling) 72 | - [Ziggurat algorithm](http://en.wikipedia.org/wiki/Ziggurat_algorithm) (any distribution with decreasing density functions) 73 | - ["The Monty Python method for generating random variables" Marsaglia & Tsang 1998](http://dl.acm.org/citation.cfm?id=292395.292453) (similar to Ziggurat, except slightly slower and doesn't require tables.) 74 | - Normal 75 | - [Box-Muller transform](https://en.wikipedia.org/wiki/Box%E2%80%93Muller_transform) and [Marsaglia polar method](https://en.wikipedia.org/wiki/Marsaglia_polar_method) (normal distribution, both are almost certainly inferior to the ziggurat algorithm) 76 | - ["Gaussian Random Number Generators" Thomas, Luk, Leong, Villasenor 2007](http://www.cse.cuhk.edu.hk/~phwl/mt/public/archives/papers/grng_acmcs07.pdf) (extremely comprehensive overview of many algorithms for normal RVs, including performance and statistical comparisons. Their conclusion is Ziggurat is fast and statistically good.) 77 | - ["Efficient generation of exponential and normal deviates" Rubin, Johnson 2006](http://dx.doi.org/10.1080/10629360500108004) (also describes/addresses deficiencies of the plain Marsaglia Ziggurat implementation) 78 | - Gamma 79 | - ["A simple method for generating gamma variables" Marsaglia & Tsang 2000](http://dl.acm.org/citation.cfm?id=358414) 80 | - ["A Simple Gamma Random Number Generator for Arbitrary Shape Parameters" Tanizaki 2008](http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.158.3866) 81 | - https://hips.seas.harvard.edu/blog/2013/02/21/a-parallel-gamma-sampling-implementation/ 82 | 83 | 84 | 85 | ### Summary of research on standards and leading techniques 86 | #### Relevant standards and techniques exist? 87 | #### Those intended to follow (and why) 88 | #### Those intended to ignore (and why) 89 | 90 | ## 3. Research of libraries from other languages 91 | 92 | 1. Language: C++11 93 | - http://www.cplusplus.com/reference/random/ 94 | 2. Language: Python 95 | - http://docs.python.org/3.3/library/random.html 96 | 3. Language: R (statistical language, so much broader random number support than necessary) 97 | - http://stat.ethz.ch/R-manual/R-patched/library/base/html/Random.html 98 | - http://stat.ethz.ch/R-manual/R-patched/library/stats/html/Distributions.html 99 | - Parallel random numbers (section 6): http://stat.ethz.ch/R-manual/R-devel/library/parallel/doc/parallel.pdf 100 | 4. Language: Julia (also a statistical language) 101 | - https://github.com/JuliaStats/Distributions.jl 102 | 4. Language: D 103 | - http://dlang.org/phobos/std_random.html (no support for sampling from distributions other than uniform, but many RNGs) 104 | 5. Language: Go 105 | - http://golang.org/pkg/math/rand/ 106 | 6. Language: Erlang 107 | - https://mail.mozilla.org/pipermail/rust-dev/2013-April/003881.html 108 | 4. Library: [GSL](https://www.gnu.org/software/gsl/manual/html_node/) 109 | - https://www.gnu.org/software/gsl/manual/html_node/Random-Number-Generation.html 110 | - https://www.gnu.org/software/gsl/manual/html_node/Random-Number-Distributions.html 111 | 5. Library: Numpy/Scipy 112 | - http://docs.scipy.org/doc/numpy/reference/routines.random.html 113 | - http://docs.scipy.org/doc/scipy/reference/stats.html 114 | 6. Library: Boost 115 | - http://www.boost.org/doc/libs/1_53_0/doc/html/boost_random/reference.html 116 | 7. Library: [RandomKit](http://js2007.free.fr/code/index.html#RandomKit) 117 | 8. Library: [Tina's Random Number Generator Library](http://numbercrunch.de/trng/) 118 | - Includes many distributions, also support for/discussion about parallel RNGs. 119 | 9. Misc: 120 | - http://tommd.github.io/posts/RNG-Bench.html 121 | - http://hackage.haskell.org/package/crypto-api (An example of a generic interface for cryptographic things, not in the scope of lib-rand, but it'd be good to not make things hard to fit into an api like this.) 122 | 123 | ### Summary of research from other languages: 124 | #### Structures and functions commonly appearing 125 | 126 | ##### Distributions: 127 | 128 | Very common/important: 129 | 130 | - Normal 131 | - Exponential 132 | - Uniform (discrete and continuous) 133 | - Gamma (many distributions are special cases/functions of this, e.g. Chi^2, F, t, beta, even uniform.) 134 | 135 | #### Variations on implementation seen 136 | #### Pitfalls and hazards associated with each variant 137 | #### Relationship to other libraries and/or abstract interfaces 138 | 139 | ## 4. Module writing 140 | 141 | - WIP: https://github.com/huonw/rust-rand 142 | - Pull request: _link to bug_ 143 | 144 | ### Additional implementation notes 145 | 146 | - `Rng` should take `&mut self`, instead of forcing the use of mutable fields 147 | - Generating many random numbers at once: methods that fill vectors, or iterators? 148 | - _note_ -------------------------------------------------------------------------------- /The-Rusticon.md: -------------------------------------------------------------------------------- 1 | This is currently a work in progress - feel free to alter or add definitions as necessary. 2 | 3 | term | definition 4 | -----|----------- 5 | algebraic data type | A type with a set of possible variants. These are declared in Rust using the `enum` keyword. More information can be found on [the Wikipedia article](http://en.wikipedia.org/wiki/Algebraic_data_type). 6 | attribute | A way of adding metadata to an item. Written as `#[attribute_name]` (other examples being `#[doc="Foo"]`, `#[doc(hidden="true")]`). 7 | bikeshed | A [highly important discussion](http://www.catb.org/jargon/html/B/bikeshedding.html) about some non-fundamental part of the language (such as syntax or identifier names). 8 | bors | The name of our continuous integration bot, a [Python script](https://github.com/graydon/bors) that checks for reviewed pull requests and runs the test on it, merging it if they pass. 9 | box | (noun) An allocated chunk of memory, (verb) To place a value in such a box 10 | built-in trait | A compiler-defined trait that is implicitly implemented for each eligible type. They are `Send`, `Share`, `Copy`, and `'static`. 11 | cargo | The official package manager for Rust programs and libraries. 12 | closure | Refers both to the type (`∣ ∣`, `proc()`) and the literal notation: `∣args∣ expression` (where expression can be a block, ie `∣x∣ { println(x.to_str()); 5}`). It is said to "close over" its environment; it can "capture" values from surrounding code. (*Note:* This is using a non-pipe unicode character because github doesn't like using that character in tables.) 13 | crate | Rust's compilation unit, a single library or executable. Is the root of a namespace. 14 | DST | [Dynamically sized type](http://smallcultfollowing.com/babysteps/blog/2014/01/05/dst-take-5/) 15 | FFI | See _foreign function interface_. 16 | foreign function interface | Calling code written in another language. Rust has a native C FFI, using `extern "C" fn`. 17 | heap allocation | A dynamic allocation not on the stack. 18 | HRTB | Higher-ranked trait bound. See [RFC 387](https://github.com/rust-lang/rfcs/blob/master/text/0387-higher-ranked-trait-bounds.md). 19 | ICE | Internal compiler error: an internal assertion failure in the compiler, which always indicates a bug in the compiler. There should never be any user input that causes an ICE to happen, so if you see one, it's always a bug and reporting it is helpful (see [[HOWTO submit a RUST bug report]]). 20 | inlining | Inlining is removal of a function call by including the function body directly into the callsite, enabling further optimizations. Controlled with the `inline` attribute: `#[inline(never)]`, `#[inline]` for a standard (though very strong) inline hint, and `#[inline(always)]`. Note that `#[inline]` is required for any cross-crate inlining. 21 | Intermediate Representation | LLVM IR Code. It can be seen in text form by passing`--emit=ir` to rustc. 22 | IR | See _Intermediate Representation_. 23 | IRFY | Is Rust Fast Yet. Graphs tracking [how long the buildbots take to build + test](http://huonw.github.io/isrustfastyet/buildbot/). Also see its companion, [Is Rust Slim Yet](http://huonw.github.io/isrustfastyet/mem/). 24 | lifetime | A piece of metadata that all references have. They represent the scope that the pointer is valid for. For more information, consult [the lifetime guide](http://static.rust-lang.org/doc/master/guide-lifetimes.html). 25 | link-time optimization | A type of optimization performed by a compiler at link time. In rustlang, link-time optimization can only be performed on executables. 26 | LTO | See _link-time optimization_. 27 | macro | A type of syntax extension, defined with `macro_rules! name_of_macro`. Are a way of declaratively generating Rust from arbitrary tokens. For example, `assert!`, `debug!`, and `fail!` are macros. The standard macros can be found [in the documentation](http://static.rust-lang.org/doc/master/std/macros/index.html). 28 | monomorphise | The act of generating specialized versions of generic constructs at compile time to improve run time performance. See [_Whole-Program Compilation in MLton_](http://mlton.org/References.attachments/060916-mlton.pdf) and [Niko Matsakis's answer on Stackoverflow](http://stackoverflow.com/a/14198060). 29 | newtype struct | A [*tuple structure*](#tuple_structure) with a single unnamed field. For example `struct NodeIndex(int)`. Useful to create wrapper types. 30 | owning pointer | `Box`, a pointer to an owned box. 31 | plain old data (Pod) | Any value that can be safely copied by moving bits, including scalars, references, and structs containing only Pod. Types which are pod implement the `Copy` trait. 32 | raw pointer | `*const T` or `*mut T`, a pointer to anything. Requires unsafe code to dereference, no static verification is done on them. 33 | record structure | A struct declared with named fields, for example `struct Point { x: f32, y: f32 }` 34 | reference | A non-owning pointer to an object. Has an associated lifetime, to assert that what it points to is always valid data. 35 | rust | Rust is named after a [fungus](http://en.wikipedia.org/wiki/Rust_%28fungus%29) that is robust, distributed, and parallel. And, Graydon is a biology nerd. See [TL;DR](http://www.reddit.com/r/rust/comments/27jvdt/internet_archaeology_the_definitive_endall_source/) 36 | rustdoc | The Rust documentation generator. 37 | rustc | The Rust source code compiler. 38 | sigil | (*Obsolete*) A character placed in front of a type, identifier or literal. In the context of Rust, this usually refered to the pointer symbols: `&`, `~`, `@`, and `*`. 39 | stack allocation | All local variables are a stack allocation. 40 | syntax extension | Code generation at compiletime, broken into three groups: declarative macros, which are described above as `macros`; procedural macros, which are written as Rust code that processes a token tree and produce an AST, and attributes. 41 | task | Rust's fundamental unit of computation. Similar to a thread. 42 | TLS | Task/Thread-Local Storage. See [these meeting minutes](https://github.com/rust-lang/meeting-minutes/blob/master/workweek-2014-08-18/libgreen-and-tls-redux.md) 43 | trait | Rust's approach to ad-hoc polymorphism, and used for generics and dynamic dispatch. Also known as [type classes](http://en.wikipedia.org/wiki/Type_class). 44 | tuple structure | A struct declared [without named fields](#record_structure), for example `struct Point(f32, f32)` 45 | TWiR | This Week in Rust. cmr's [weekly summary](http://blog.octayn.net/) of Rust's development. 46 | type hint | Syntax like `foo::()` to give an explicit type for a generic function, method or struct constructor. Usually redundant due to type inference. 47 | unbox | To get the value out of a box, usually destroying the box in the process. 48 | unit type | The unit type, denoted `()`, permits only one value, also denoted `()`. Functions without return value have return type `()`. Sometimes called *nil*. 49 | uninhabited type | An `enum` with no variants. This cannot be constructed in safe code. 50 | unit structure | A struct that only has one value, for example `struct Foo;` where `Foo` becomes the name of both the type and its only value. Works just the same as the *unit type* `()`, except it is a distinct type. 51 | variant | One of the set of possible values that can be represented by an `enum`. 52 | zero-variant enum | See [*phantom type*](#phantom_type). 53 | 54 | ## Syntaxicon 55 | 56 | What is this syntax called? 57 | 58 | *Note*: these names represent the current consensus on desired naming by #rust-internals and brson. Ask there before changing them. 59 | 60 | syntax | name 61 | -------|----------- 62 | `()` | The [*unit type*](#unit_type). 63 | `'static`, `'a` | A *lifetime*. May also be used to name a `loop` or a `for` clause (a label). 64 | `Box` | If `T` is a type, an *owning pointer* to `T`, and the pointer is to an *owned box*. 65 | `&T`, `&'a T` | If `T` is a type, a [*reference*](#reference) to `T`, possibly with a *lifetime* (`'a`). 66 | `∣ ∣`, `∣T∣ -> U` | A [*closure*](#closure). 67 | `&[T]`, `&'a [T]` | A *slice* with element type `T` and possibly with a *lifetime*. 68 | `&mut [T]`, `&'a mut [T]` | A *mutable slice* with element type `T` and possibly with a *lifetime*. One can borrow a `&mut` to the elements of the slice. 69 | `[T, ..n]` | An *array* of length `n`. 70 | `[T]` | An *array* whose length is unknown (a dynamically-sized type). 71 | `Box:Send`, `&'a Trait:Send` | A *trait object* where `:Send` are the *kind bounds*. 72 | `foo!()` | Either a [*macro*](#macro) or *syntax extension*. 73 | `#[xyz]`, `#![xyz]` | An [*attribute*](#attribute). 74 | `::`, `: int` (in `let x: int ...`) | A [*type hint*](#type_hint). 75 | 76 | ## Taking Arguments 77 | 78 | AKA: "Help, where do I put the `mut`?" 79 | 80 | There are a few combinations: 81 | 82 | ```rust 83 | fn A(x: T) { } 84 | fn B(x: &T) { } 85 | fn C(x: &mut T) { } 86 | fn D(mut x: T) { } 87 | fn E(mut x: &T) { } 88 | fn F(mut x: &mut T) { } 89 | ``` 90 | 91 | The `mut` before the `x` refers to the *binding*, whereas the `mut` after the `&` refers to *aliasability*. Only one `&mut` may exist to a given value at a given time, which means you are free to mutate it as you please. When a binding a mutable, you may reassign, so in `D` through `F`, in the body of the function you could write `x = foo();`. In `A` and `D`, the type is passed by-value, and if the type is "affine", it will be moved. The opposite of "affine" is "Copy", or "POD" (plain-old-data, jacked from C++), and these types will be copied rather than moved. That is, `A` and `D` would get a fresh copy that, if they mutated, the caller would not see the mutations. Additionally, `D` would be able to mutate `x` willy-nilly, as opposed to `A`, which would need a `let mut y = x;` or similar. 92 | 93 | `B` and `E` take shared references. These are "aliasable" references, and multiple shared references can point at the same data at the same time. Any mutations that happen through a `&T` need to be safe in the face of this! Doing so is called "internal mutability", and is how the `RefCell` type works. -------------------------------------------------------------------------------- /Library-editing.md: -------------------------------------------------------------------------------- 1 | # Library-editor's guide 2 | 3 | The modules in the Rust standard library are of widely varying quality, completeness and coherence. This page provides guidelines and a process to aspiring "library editors" who want to _substantially_ improve, complete and standardize library modules. That is, those who want to take some degree of ownership over planning, organizing, editing and reviewing part of the Rust standard libraries. 4 | 5 | If you have a small edit to make (a minor bug-fix or API-addition) or do not wish to have an ongoing organizational role in terms of editing libraries, this page is probably not relevant to you. Open a pull request and a library editor or project reviewer will take a look. 6 | 7 | If this page _is_ relevant, we ask that you **please follow the guidelines in this page** when structuring your work. Library work has tendencies towards accidental duplication of effort, repetition of effort, and multiple conflicting implementations or attempts. Our goals with these guidelines are: 8 | - to minimize the unfortunate tendencies of library work stated above 9 | - to expedite approval of library work by setting expectations and authorizing new "library editors" to review changes for automated merging 10 | - to give library editors a sense of structure to work within and criteria to evaluate one another's work against 11 | 12 | There are two kinds of library-editing work to consider: 13 | 14 | * "General" work of improving code quality across all (or many) modules, regardless of topic. 15 | * "Topical" work related to a specific module (or group of modules), informed by its area of focus. 16 | 17 | For each type of work, we provide a sequence of steps which you should take if you want to work on a library. Following these steps will improve the odds of others in the community noticing your work, providing timely and relevant input, cooperating rather than working across-purposes, and producing results that get merged into our repository easily. 18 | 19 | ## General cross-module cleanup 20 | 21 | There are many quality issues (interface consistency, obsolete idioms, non-conformance to the module edit criteria) that require many small patches applied over many different modules. These should be addressed by the following steps: 22 | 23 | 1. Announce your intention to produce guidelines on the issue. This should take the form of an email to the mailing list with with "cleanup:" in the subject. 24 | 2. Discuss for 1 week on mailing list to solicit input from others on the issue. 25 | 3. Make a wiki page describing instances of the issue and how to solve them, collecting together point-form comments from the mailing list discussion. Add it to the **Active Module Edit Plans** section of [[Libs]]. 26 | 4. Request the core project members approve of this cleanup task. It will get discussed and either approved or rejected at the next weekly meeting. 27 | 28 | Once approved-of, a category of library cleanup can be used to expedite pull requests. In particular, put "cleanup:" in the title of the pull request and address _only_ a project-approved cleanup task in your pull request, and library editors can approve such changes for automated merging. 29 | 30 | ## Topical module-improvements 31 | 32 | When you want to work on one or more _particular_ modules, due to wanting better library code for the topic the module is concerned with, we ask that you follow a relatively structured process involving research, consultation and (relatively) objective criteria. There are 5 main steps to follow: 33 | 34 | 1. Announce your intention on the mailing list, make a page on the wiki. Discuss on the mailing list for 1 week. 35 | 2. Research relevant standards (see below). 36 | 3. Research relevant libraries in other languages (see below). 37 | 4. Write or reorganize the modules in question based on the library criteria given in this page (see below). 38 | 5. Get another library-editor (or committer / reviewer) to review your module. 39 | 40 | ### 1. Announce your intention 41 | 42 | - Send an email to the mailing list stating your intention to work on a library and/or assume a library-editing role. This should take the form of an email to the mailing list with with "lib:" in the subject. 43 | - Make a copy of the [[module edit plan template|Lib template]] and add it to the **Active Module Edit Plans** section of [[Libs]]. 44 | - Put a link to the email in the template and note the date. 45 | - Discuss for _one week_ with the mailing list. Free-form discussion. Fish for ideas. See who else is interested. 46 | - **During this period, accept the possibility of veto**. If there is strong disagreement that the work you're proposing live in the standard library, you should probably keep it in an external package. 47 | - Assuming there is general consensus on the desirability of the module and your stewardship of it: make a short list of salient people and ideas that came up during that week in your module edit plan. 48 | - If you requested it, you may at this point (subject to consensus of the core developers) also be added to the list of reviewers bors listens to, as a library editor. **Please exercise restraint in review and focus on library edits**. Library-editing is a middle role between non-authorized contributors and core developers, and should not be used to review your own work, or work outside the libraries. 49 | 50 | ### 2. Survey existing standards and techniques 51 | 52 | - You can start this during the week of free-form discussion. 53 | - Go through any of the following standards organizations looking for documents pertaining to your module: 54 | - http://standards.iso.org/ittf/PubliclyAvailableStandards/index.html 55 | - http://standards.ieee.org/findstds/index.html 56 | - http://www.ecma-international.org/publications/standards/Standard.htm 57 | - http://www.apps.ietf.org/rfc/stdlist.html 58 | - http://www.unicode.org/reports/ 59 | - http://www.w3.org/standards/ 60 | - http://www.oasis-open.org/standards 61 | - http://en.wikipedia.org/wiki/Single_UNIX_Specification 62 | - http://en.wikipedia.org/wiki/Open_format 63 | - http://en.wikipedia.org/wiki/Free_file_format 64 | - http://en.wikipedia.org/wiki/Cryptography_standards 65 | - Go through any of the following lists looking for _techniques_ related to your module: 66 | - http://xlinux.nist.gov/dads/ 67 | - http://en.wikipedia.org/wiki/List_of_algorithms 68 | - http://en.wikipedia.org/wiki/List_of_data_structures 69 | - http://en.wikipedia.org/wiki/List_of_file_formats 70 | - If you find such standards or techniques, _read them_. 71 | - Place links to such standards in your module edit plan. 72 | - Summarize in point-form the recommendations, leading techniques, industrial or academic standards you intend to follow or deviate from, and why. If no relevant standards exist, note this fact. 73 | 74 | ### 3. Survey existing languages 75 | 76 | - You can start this during the week of free-form discussion. 77 | - Look through at least 4, preferably 5 or 6 of the following other language ecosystems and standard libraries for libraries on the same topic: 78 | - C: 79 | - http://www.cplusplus.com/reference/clibrary/ 80 | - http://www.gnu.org/software/libc/manual/html_mono/libc.html 81 | - C++: 82 | - http://en.cppreference.com/w/cpp 83 | - http://www.boost.org/doc/libs/1_53_0/libs/libraries.htm 84 | - C#: 85 | - http://msdn.microsoft.com/en-us/library/aa388745.aspx 86 | - D: 87 | - http://dlang.org/phobos/index.html 88 | - Java: 89 | - http://docs.oracle.com/javase/7/docs/api/ 90 | - Scala: 91 | - http://www.scala-lang.org/api/current/index.html 92 | - http://www.scala-lang.org/node/1209 93 | - Go: 94 | - http://golang.org/pkg/ 95 | - https://code.google.com/p/go-wiki/wiki/Projects 96 | - Haskell: 97 | - http://www.haskell.org/ghc/docs/latest/html/libraries/index.html 98 | - http://hackage.haskell.org/packages/archive/pkg-list.html 99 | - OCaml: 100 | - http://caml.inria.fr/pub/docs/manual-ocaml-4.00/libref/Pervasives.html 101 | - http://caml.inria.fr/pub/docs/manual-ocaml-4.00/manual035.html 102 | - Ada: 103 | - http://www.ada-auth.org/standards/12rm/html/RM-A.html 104 | - Scheme: 105 | - http://srfi.schemers.org/ 106 | - http://planet.racket-lang.org/ 107 | - http://wiki.call-cc.org/chicken-projects/egg-index-4.html 108 | - Common Lisp: 109 | - http://www.lispworks.com/documentation/HyperSpec/Front/Contents.htm 110 | - http://clocc.sourceforge.net/ 111 | - Python: 112 | - http://docs.python.org/3.2/py-modindex.html 113 | - http://pypi.python.org/pypi 114 | - Ruby: 115 | - http://www.ruby-doc.org/stdlib-1.9.3/ 116 | - https://rubygems.org/gems 117 | - Place links to relevant source code, library or class names. 118 | - Summarize in point-form the following: 119 | - Structures and functions commonly appearing 120 | - Variations on implementation seen 121 | - Pitfalls and hazards associated with each variant 122 | - Relationship to other libraries and/or abstract interfaces 123 | 124 | ### 4. Write or edit the module 125 | 126 | Modules should generally aim to satisfy these criteria: 127 | - Adequate surveying of standards has been done and documented 128 | - Put a doc-comment discussing such standards in the module. 129 | - Conform to any surveyed standards / leading techniques when possible. 130 | - **Avoid any patented techniques, and do not copy nonfree code** 131 | - Intersect, don't union, APIs found in other languages. When in doubt, do less at first, grow later. 132 | - Separate "one best variant" of an API from "several optional variants" 133 | - Give the most discoverable / obvious name to the "one best variant", give others less obvious names or place in submodules. 134 | - Priorities: docs > correctness > simplicity > speed. 135 | - Include `#[test]` based unit tests: 136 | - Those from from spec documents or behavior in other languages. 137 | - Randomly generated tests. 138 | - Hand-written tests. 139 | - Include `#[bench]` based benchmarks if possible 140 | - Minimize mutable state. 141 | - Minimize unsafe code. 142 | - Minimize heap allocation. 143 | - Minimize size and complexity of traits. 144 | - Minimize non-portable or platform-specific code. 145 | - Separately implement Owned variant and Managed variant when reasonable forms of both exist. 146 | - Similarly (possibly same as above), implement mutable/freezable variant separately from persistent/functional 147 | - Reuse other parts of standard libraries when possible. 148 | - Factor out common traits when >2 implementations exist. 149 | - Follow [[naming conventions|Lib naming conventions]] 150 | 151 | ### 5. File a pull request and ask another library editor or core developer for review 152 | 153 | The reviewer should be reminded to evaluate your module on the criteria above. If a module is satisfactory in terms of these criteria, it should be merged. 154 | -------------------------------------------------------------------------------- /Note-getting-started-developing-Rust.md: -------------------------------------------------------------------------------- 1 | This page describes how to download and build the Rust compiler and 2 | associated tools and libraries from the current git sources. If 3 | you're more interested in _using_ Rust than in hacking on the Rust 4 | compiler, you might prefer to install a prebuilt snapshot from [here](http://www.rust-lang.org/install.html), following 5 | the instructions in the [guide](http://doc.rust-lang.org). 6 | For Windows users, see [[Using Rust on Windows]]. 7 | 8 | ## Prerequisites 9 | 10 | 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. 11 | 12 | * A recent Linux, OS X (10.6 or later), Win32 or FreeBSD system 13 | * 1.5 GiB RAM _available for the build process_ (see note below about memory usage) 14 | * [`python` 2.x](http://www.python.org/download/) (version 2.7 is known to work) 15 | * GNU `make` 3.81 16 | * `git` 1.7 17 | * `g++` 4.7 at least on Linux, 4.5 on Windows, and the 4.x `gcc` in Apple's SDK for OS X. 18 | * `curl` 19 | * recommended: `valgrind` 3.8.0 or later (not required for Linux) 20 | * optional: if you wish to build LaTeX PDF docs, [`pandoc`](http://johnmacfarlane.net/pandoc/) 1.9.1 at least, with one or more of `pdflatex`/`xelatex`/`lualatex` 21 | * optional: `ccache` to shorten your rebuild times 22 | 23 | ### Memory usage 24 | 25 | 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. 26 | 27 | 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. 28 | 29 | ### Debian-based Linux Distributions 30 | 31 | You can install all the prerequisites you need to build Rust by running: 32 | 33 | ~~~~bash 34 | sudo apt-get install python make git g++ curl valgrind 35 | ~~~~ 36 | 37 | For Ubuntu users willing to build LaTeX doc, you will need some more packages: 38 | 39 | ~~~~bash 40 | sudo apt-get install pandoc texlive-latex-recommended lmodern 41 | ~~~~ 42 | 43 | The `pandoc` that's packaged with certain Linux 44 | distributions (Ubuntu, for instance) is sometimes quite old, 45 | so make sure that it's at least version 1.9.1 (you can check 46 | the version by running `pandoc -V`). If your version's too old, follow the building 47 | instructions [here](http://johnmacfarlane.net/pandoc/installing.html). 48 | Also, make sure you have the `lmodern` font package (see [#3989](https://github.com/mozilla/rust/issues/3989)). 49 | 50 | ### Windows 51 | 52 | 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](http://sourceforge.net/projects/msys2/), which also provides a convenient package manager. You can install the compiler toolchain using MSYS2's package manager. 53 | 54 | (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](http://sourceforge.net/mailarchive/message.php?msg_id=29801372).) 55 | 56 | 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. 57 | 58 | #### 32-bit build 59 | 60 | Execute `mingw32_shell.bat` to run MSYS2 for a 32-bit system. Run the following commands: 61 | 62 | pacman -S mingw-w64-i686-toolchain 63 | pacman -S base-devel 64 | pacman -S git 65 | 66 | To check the installation was successful, type `gcc -v`. The target should be `i686-w64-mingw32`. 67 | 68 | Now everything is ready, `cd` into the Rust source directory and run: 69 | 70 | ./configure 71 | make 72 | 73 | This will start the Rust build. 74 | 75 | #### 64-bit build 76 | 77 | Execute `mingw64_shell.bat` to run MSYS2 for a 64-bit system. Run the following commands: 78 | 79 | pacman -S mingw-w64-x86_64-toolchain 80 | pacman -S base-devel 81 | pacman -S git 82 | 83 | To check the installation was successful, type `gcc -v`. The target should be `x86_64-w64-mingw32`. 84 | 85 | ### OSX 86 | 87 | Get the command line tools for Xcode from [Apple Developer Downloads](https://developer.apple.com/downloads/index.action), or open Xcode and go to Xcode -> Preferences -> Downloads -> Components. 88 | 89 | Then optionally install Valgrind and pandoc. Valgrind is available from [homebrew]: `brew install valgrind`. pandoc must be installed manually according to the [installation instructions](http://johnmacfarlane.net/pandoc/installing.html). ccache can also be installed from [homebrew]: `brew install ccache`. 90 | 91 | [homebrew]: http://brew.sh/ 92 | 93 | Sometimes, on OS X, compiling Rust might fail with a "too many open files" error, especially when running `make check`. 94 | * 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`. 95 | * 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: 96 | 97 | 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`: 98 | 99 | ~~~~ 100 | kern.maxfiles=1048600 101 | kern.maxfilesperproc=1048576 102 | ~~~~ 103 | 104 | 2. Raise the launchd limits: `sudo launchctl limit maxfiles 1048576`. Can be made persistent by adding ` limit maxfiles 1048576` to `/etc/launchd.conf`. 105 | 106 | 3. Verify the changes. If all goes well, `sudo launchctl limit` should show something like this: 107 | 108 | ~~~~ 109 | [...] 110 | maxproc 709 1064 111 | maxfiles 1048575 1048575 112 | ~~~~ 113 | 114 | 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. 115 | 116 | ### FreeBSD 117 | 118 | 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: 119 | 120 | ~~~~bash 121 | pkg_add -r git gmake libexecinfo libunwind 122 | ~~~~ 123 | 124 | 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`. 125 | 126 | ### Android 127 | 128 | See [[building for Android|Doc-building-for-android]] 129 | 130 | ## Downloading and Building Rust 131 | 132 | Before you get started, you should quickly review the [build system notes](https://github.com/rust-lang/rust/blob/master/Makefile.in#L11) which describes the Make targets, among other things. 133 | 134 | ~~~~bash 135 | git clone git://github.com/mozilla/rust.git 136 | cd rust 137 | ~~~~ 138 | 139 | Make sure prerequisites, such as Python or Perl, can be found via the `PATH` environment variable, otherwise you will get errors during `./configure`. 140 | 141 | The `configure` script will pull git submodules if it's the first time. This may take a while. 142 | 143 | **`--enable-rpath`:** By default, the newly built `rustc` found in `/stage/bin/` will likely have its shared library dependencies pointing to the system-wide library path e.g. `/usr/lib/`. This could be problematic if you do not intend to `make install` the shared library dependencies to that destination. Pass `--enable-rpath` to `configure` to make `rustc` link against the newly built libraries in `/stage/bin/`. Alternatively, you can muck around with `LD_LIBRARY_PATH`. See [#20835](/rust-lang/rust/issues/20836) for more details. 144 | 145 | To adjust the install locations, pass `--prefix=/path/to/install/dir` to `configure`. 146 | 147 | Run `./configure --help` for various other options. 148 | 149 | ~~~~bash 150 | ./configure --enable-rpath 151 | ~~~~ 152 | 153 | Build the compiler, standard libraries, and supporting tools. 154 | 155 | You can use `make -j` to run a parallel build utilizing all available cores. You can also specify the number of cores to use e.g. `make -j8` for an 8-core machine. 156 | 157 | ~~~~bash 158 | make 159 | ~~~~ 160 | 161 | Optional steps: 162 | 163 | Run the test suite. On windows, `make check` may not pass. In any case, `make check-fast` should work (see [#4193](/rust-lang/rust/issues/4193)). 164 | 165 | *Note:* 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. 166 | 167 | ~~~~bash 168 | make check 169 | ~~~~ 170 | 171 | Install the compiler and associated tools. You may need to use `sudo make install` if you do not normally have permission to modify the destination directory. 172 | 173 | ~~~~bash 174 | make install 175 | ~~~~ 176 | 177 | *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. 178 | 179 | *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. 180 | 181 | ## Navigating 182 | 183 | There's a quick guide to the source of the compiler in [src/librustc/README.txt](https://github.com/mozilla/rust/blob/master/src/librustc/README.txt). You should look through it if you're planning on contributing. 184 | 185 | ## Editor support 186 | 187 | Syntax highlighting for vim is located at the [rust.vim](https://github.com/rust-lang/rust.vim) repository, and syntax highlighting for emacs is located at the [rust-mode](https://github.com/rust-lang/rust-mode) repository. Other editors may [[also be supported|Doc packages, editors, and other tools]]. 188 | 189 | ## The issue tracker 190 | 191 | We use the [GitHub issue tracker](https://github.com/mozilla/rust/issues) 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](http://githubissues.heroku.com/#mozilla/rust) that is quite a bit more responsive. 192 | 193 | ## Communicating 194 | 195 | 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). 196 | 197 | Join the [mailing list](https://mail.mozilla.org/listinfo/rust-dev) for longer conversations. 198 | 199 | In both cases, please follow the conduct guidelines on the [[development policy|Note development policy]]. -------------------------------------------------------------------------------- /Doc-friends-of-the-tree.md: -------------------------------------------------------------------------------- 1 | At the [weekly meeting](https://github.com/rust-lang/meeting-minutes) 2 | The Rust Team likes to occassionally recognize people who have made 3 | outstanding contributions to The Rust Project, its ecosystem, and its 4 | community. These people are 'friends of the tree', archived here 5 | for eternal glory. 6 | 7 | ## 2015-03-03 Manish Goregaokar (Manishearth) 8 | 9 | Manish started working on Servo as part of the GSoC program in 2014, where he implemented XMLHttpRequest. Since then he's become in integral part of the Servo team while finishing his university studies and organizing Rust community events. In 2015 he took an interest in bors' queue and started making rollup PRs to accelerate the integration process. Nursing the PR queue is the kind of time-consuming labor that creates friends of the tree like Manish, the rollup friend of the tree. 10 | 11 | ## 2015-02-17 Toby Scrace 12 | 13 | Today I would like to nominate Toby Scrace as Friend of the Tree. Toby emailed me over the weekend about a login vulnerability on crates.io where you could log in to whomever the previously logged in user was regardless of whether the GitHub authentication was successful or not. I very much appreciate Toby emailing me privately ahead of time, and I definitely feel that Toby has earned becoming Friend of the Tree. 14 | 15 | ## 2015-02-10 Jonathan Reem (reem) 16 | 17 | Jonathan Reem has been making an impact on Rust since May 2014. His 18 | primary contribution has been as the main author of the prominent 19 | [Iron][iron] web framework, though he has also created several other 20 | popular projects including the testing framework [stainless]. His 21 | practical experience with these projects has led to several 22 | improvements in upstream rust, most notably his complete rewrite of 23 | the `TaskPool` type. Reem is doing everything he can to advance 24 | the Rust cause. 25 | 26 | [iron]: https://github.com/iron/iron 27 | [stainless]: https://github.com/reem/stainless 28 | 29 | ## 2015-01-20 Barosl Lee (barosl) 30 | 31 | Today I would like to nominate Barosl Lee (@barosl) for Friend of the Tree. Barosl has recently rewritten our bors cron job in a new project called [homu]. Homu has a number of benefits including: 32 | 33 | - Zero "down time" between testing different PRs (compared to 30+ minutes for bors!) 34 | - A new rollup button to create separate rollup PRs from other PRs. 35 | - Multiple repositories are supported (Cargo and Rust are on the same page) 36 | 37 | Homu was recently deployed for rust-lang/rust thanks to a number of issues being closed out by Barosl, and it's been working fantastically so far! Barosl has also been super responsive to any new issues cropping up. Barosl truly is a Friend of the Tree! 38 | 39 | [homu]: https://github.com/barosl/homu 40 | 41 | ## 2015-01-13 Kang Seonghoon (lifthrasiir, Yurume) 42 | 43 | Seonghoon has been an active member of the Rust community since early 44 | 2013, and although he has made a number of valuable contributions to 45 | Rust itself, his greatest work has been in developing key libraries 46 | out of tree. [rust-encoding], one of the most popular crates in Cargo, 47 | performs character encoding, and [rust-chrono] date / time handling, 48 | both of which fill critical holes in the functionality of the standard 49 | library. [rust-strconv] is a prototype of efficient numerical string 50 | conversions that is a candidate for future inclusion in the standard 51 | library. He maintains a [blog][rustlog] where he discusses his work. 52 | 53 | [rust-encoding]: https://github.com/lifthrasiir/rust-encoding 54 | [rust-strconv]: https://github.com/lifthrasiir/rust-strconv 55 | [rust-chrono]: https://github.com/lifthrasiir/rust-chrono 56 | [rustlog]: https://lifthrasiir.github.io/rustlog/ 57 | 58 | 59 | ## 2015-01-06 Jorge Aparicio (japaric) 60 | 61 | I nominate Jorge Aparicio (japaric) for Friend of the Tree (for the second time, no less!). japaric has done tremendous work porting the codebase to use the new language features that are now available. First, he converted APIs in the standard library to take full advantage of DST after it landed. Next, he converted APIs to use unboxed closures. Then, he converted a large portion of the libraries to use associated types. Finally, he removed boxed closures from the compiler entirely. He has also worked to roll out RFCs changing the overloaded operators and comparison traits, including both their definitions and their impact on the standard library. And this list excludes a number of smaller changes, like deprecating older syntax. The alpha release would not be where it is without him; Japaric is simply one of the best friends the tree has ever had. 62 | 63 | ## 2014-12-30 Kevin Ballard (kballard, Eridius) 64 | 65 | This is a belated recognition of Kevin Ballard (aka @kballard, aka Eridius) as a friend of the tree. Kevin put a lot of work into Unicode issues in Rust, especially as related to platform-specific constraints. He wrote the current path module in part to accommodate these constraints, and participated in the recent redesign of the module. He has also been a dedicated and watchful reviewer. Thanks, Kevin, for your contributions! 66 | 67 | ## 2014-12-16 Gábor Lehel (glaebhoerl) 68 | 69 | Gabor's major contributions to Rust have been in the area of language 70 | design. In the last year he has produced a number of very high quality 71 | RFCs, and though many of them of not yet been accepted, his ideas are 72 | often thought-provoking and have had a strong influence on the 73 | direction of the language. His [trait based exception handling 74 | RFC][tbeh] was particularly innovative, as well that [for 75 | future-proofing checked arithmetic][checked]. Gabor is an exceedingly 76 | clever Friend of the Tree. 77 | 78 | [tbeh]: https://github.com/rust-lang/rfcs/pull/243 79 | [checked]: https://github.com/rust-lang/rfcs/pull/146 80 | 81 | ## 2014-11-11 Brian Koropoff (unwound) 82 | 83 | In the last few weeks, he has fixed many, many tricky ICEs all over the compiler, but particularly in the area of unboxed closures and the borrow checker. He has also completely rewritten how unboxed closures interact with monomorphization and had a huge impact on making them usable. Brian Koropoff is truly a Friend of the Tree. 84 | 85 | ## 2014-10-07 Alexis Beingessner (Gankro) 86 | 87 | Alexis Beingessner (aka @Gankro) began contributing to Rust in July, 88 | and has already had a major impact on several library-related 89 | areas. His main focus has been collections. He completely rewrote 90 | BTree, providing a vastly more complete and efficient 91 | implementation. He proposed and implemented the new Entry API. He's 92 | written extensive new documentation for the collections crate. He 93 | pitched in on collections reform. 94 | 95 | And he added collapse-all to rustdoc! 96 | 97 | Alexis is, without a doubt, a FOTT. 98 | 99 | ## 2014-09-02 Jorge Aparicio (japaric) 100 | 101 | Jorge has made several high-impact contributions to the wider Rust community. 102 | He is the primary author of rustbyexample.com, and last week published 103 | "eulermark", a comparison of language performance on project Euler problems, 104 | which happily showed Rust performing quite well. 105 | As part of his benchmarking work he has ported the 'criterion' benchmarking 106 | framework to Rust. 107 | 108 | ## 2014-07-29 Björn Steinbrink (dotdash, doener) 109 | 110 | Contributing since April 2013. Björn has done many optimizations 111 | for Rust, including removing allocation bloat in iterators, 112 | fmt, and managed boxes; optimizing `fail!`; adding strategic 113 | inlining in the libraries; speeding up data structures in 114 | the compiler; eliminating quadratic blowup in translation, 115 | and other IR bloat problems. 116 | 117 | He's really done an amazing number of optimizations to Rust. 118 | 119 | Most recently he earned huge kudos by teaching LLVM about 120 | the lifetime of variables, allowing Rust to make much more 121 | efficient use of the stack. 122 | 123 | Björn is a total FOTT. 124 | 125 | ## 2014-07-22 Jonas Hietala (treeman) 126 | 127 | Jonas Hietala, aka @treeman, has been contributing a large amount of 128 | documentation examples recently for modules such as hashmap, treemap, 129 | priority_queue, collections, bigint, and vec. He has also additionally 130 | been fixing UI bugs in the compiler such as those related to format! 131 | 132 | Jonas continues to add new examples/documentation every day, making 133 | documentation more approachable and understandable for all 134 | newcomers. Jonas truly is a friend of the tree! 135 | 136 | ## 2014-07-08 Sven Nilson (bvssvni, long_void) 137 | 138 | Sven Nilson has done a great deal of work to build up the Rust crate ecosystem, 139 | starting with the well-regarded rust-empty project that provides boilerplate build 140 | infrastructure and - crucially - integrates well with other tools like Cargo. 141 | 142 | His Piston project is one of the most promising Rust projects, and its one that 143 | integrates a number of crates, stressing Rust's tooling at just the right time: 144 | when we need to start learning how to support large-scale external projects. 145 | 146 | Sven is a friend of the tree. 147 | 148 | ## 2014-06-24 Jakub Wieczorek (jakub-) 149 | 150 | jakub-, otherwise known as Jakub Wieczorek, has recently been working 151 | very hard to improve and fix lots of match-related functionality, a 152 | place where very few dare to venture! Most of this code appears to be 153 | untouched for quite some time now, and it's receiving some 154 | well-deserved love now. 155 | 156 | Jakub has fixed 10 bugs this month alone, many of which have been 157 | long-standing problems in the compiler. He has also been very 158 | responsive in fixing bugs as well as triaging issues that come up from 159 | fun match assertions. 160 | 161 | Jakub truly is a friend of the tree! 162 | 163 | ## 2014-04-22 klutzy 164 | 165 | klutzy has been doing an amazing amount of Windows work for years 166 | now. He picks up issues that affect our quality on Windows and picks 167 | them off 1 by 1. It's tedious and doesn't get a ton of thanks, but is 168 | hugely appreciated by us. As part of the Korean community, he has also 169 | done a lot of work for the local community there. He is a friend of 170 | the tree. Thank you! 171 | 172 | - Rust on Windows crusader 173 | - Fixed issues with x86 C ABI struct arguments 174 | - Fixed multiple issues with non-US locales 175 | 176 | ## 2014-03-18 Clark Gaebel (cgaebel) 177 | 178 | This week's friend of the tree is Clark Gaebel. He just landed a huge 179 | first contribution to Rust. He dove in and made our hashmaps 180 | significantly faster by implementing Robin Hood hashing. He is an 181 | excellent friend of the tree. 182 | 183 | ## 2014-02-25 Erick Tryzelaar (erickt) 184 | 185 | - Contributing since May 2011 186 | - Wrote the serialization crate 187 | - Organizes the bay area Rust meetups 188 | - Just rewrote the Hash trait 189 | 190 | ## 2014-02-11 Flavio Percoco (FlaPer87) 191 | 192 | - Contributing since September 193 | - Does issue triage 194 | - Organizing community events in Italy 195 | - Optimized the 'pow' function 196 | - Recently been fixing lots of small but important bugs 197 | 198 | ## 2014-01-27 - Jeff Olson (olsonjefferey) 199 | 200 | - Contributing since February 2012 201 | - Did the original libuv integration 202 | - Implemented our second attempt at I/O, first using libuv 203 | - Ported parts of the C++ runtime to Rust 204 | - Implemented file I/O for the newest runtime 205 | - Last week published an article about file I/O on the Safari books blog 206 | 207 | ## 2014-01-21 - Steven Fackler (sfackler) 208 | 209 | - Contributing since last May 210 | - CMU grad 211 | - Lots of library improvements, Base64, Bitv, I/O 212 | - Rustdoc improvements 213 | - Mut/RefCell 214 | - std::io::util 215 | - external module loading 216 | 217 | ## 2014-01-14 - Eduard Burtescu (eddyb) 218 | 219 | - Contributing since October 220 | - Working on the compiler, including trans 221 | - Reduced rustc memory usage 222 | - Optimized vector operations 223 | - Helping refactor the compiler to eliminate use of deprecated features 224 | - Cleaned up ancient code in the compiler 225 | - Removed our long-standing incorrect use of the environment argument to pass the self param 226 | 227 | ## 2014-01-07 - Vadim Chugunov (vadimcn) 228 | 229 | - Contributing since June 230 | - Fixed numerous bugs on Windows 231 | - Fixing broken tests 232 | - Improved compatibility with newer mingw versions 233 | - Eliminated our runtime C++ dependency by implementing unwinding through libunwind -------------------------------------------------------------------------------- /Note-testsuite.md: -------------------------------------------------------------------------------- 1 | # The Rust test suite 2 | 3 | The rust test suite has several sets of tests for different purposes. As the compiler is built over multiple stages, and with varying host and target combinations, debugging and profiling settings, the tests can be run in many different ways. 4 | 5 | ### Recipes 6 | 7 | * Run the test suite: `make check`. This runs all stage2 tests. This is the criterion for a successful build. 8 | * Run the test suite with benchmarks: `make check PLEASE_BENCH=1` 9 | * Run only ignored (broken) tests: `make check CHECK_IGNORED=1` 10 | * Run with verbose output: `make check VERBOSE=1`. This will print useful information like the exact commands being run. 11 | * Run with valgrind: `make check CFG_ENABLE_VALGRIND=1` 12 | * Run a specific test: `make check TESTNAME=[...]` 13 | * The pattern `[...]` can be a complete path to a test, such as 14 | `run-pass/foobar.rs`; it can also be any substring of a path. 15 | For instance, `make check TESTNAME=foo` will run all tests that 16 | have `foo` in some part of their filename. 17 | * Note that while this will run only tests matching the given 18 | pattern, it will still execute all test runners - most of them 19 | will just not execute any tests. For more precise control, call 20 | `make` on one of the targets below. 21 | * You may need to `touch` the test source file to ensure that `make` 22 | runs the necessary test runners. 23 | * Run without parallelism: `make check RUST_TEST_TASKS=1` - This can make it easier to understand failure output. 24 | * Build and test std without re-bootstrapping: `make check-stage1-std NO_REBUILD=1` - This makes the build/test cycle **much** faster. (Note: `NO_REBUILD` can also prevent compile tests from being rebuilt. If you want to rebuild those but not the compiler, look for files with the `.ok` extension in the `tmp` subdirectory and remove the appropriate ones.) 25 | 26 | These options can be combined. For instance, `make check CHECK_IGNORED=1 TESTNAME=test/run-pass/foobar.rs` runs the ignored test `foobar.rs` in the `run-pass` directory. 27 | 28 | ## Language and compiler tests 29 | 30 | These are tests of the compiler against Rust source code. They typically have a `main` function that takes no arguments and may have directives that instruct the test runner how to run the test. These tests may be compiled and executed, pretty-printed, jitted, etc. depending on the test configuration. 31 | 32 | The test runner for these tests is at src/test/compiletest and is compiled to test/compiletest.stage[N]. 33 | 34 | A typical test might look like: 35 | 36 | ```rust 37 | // ignore-pretty 'bool' doesn't pretty-print (#XXX) 38 | // Regression test for issue #YYY 39 | 40 | fn main() { 41 | let a: bool = 10; //~ ERROR mismatched types 42 | } 43 | ``` 44 | 45 | There are seven different modes for compile tests. Each test is run under one or more modes: 46 | 47 | * compile-fail - The test should fail to compile. Must include at least one expected error. 48 | * run-fail - The test should compile but fail at runtime. Must include at least one error-pattern directive. 49 | * run-pass - The test should compile and run successfully 50 | * run-pass-valgrind - The test should compile and run (under Valgrind, where possible) successfully 51 | * pretty - The test should round-trip through the pretty-printer and then compile successfully 52 | * debug_info - The test will be compiled with debuginfo and an embedded `gdb` command script will be run to query the debuginfo 53 | * codegen - The test will be compiled to LLVM bitcode, and a companion test written in C++ will be compiled to LLVM bitcode with `clang`, and the number of instructions will be compared 54 | 55 | Valid directives include: 56 | 57 | * `compile-flags:[...]` - Additional arguments to pass to the compiler 58 | * `pp-exact` - The test should pretty-print exactly as written 59 | * `pp-exact:[filename]` - The pretty-printed test should match the example in `filename` 60 | * `ignore-test` - Test is broken, don't run it 61 | * `ignore-pretty` - Test doesn't pretty-print correctly 62 | * `error-pattern:[...]` - A message that should be expected on standard out. If multiple patterns are provided then they must all be matched, in order (**Note:** error-patterns are somewhat deprecated, see the section on Expected Errors below). 63 | * `no-reformat` - Don't reformat the code when running the test through the pretty-printer 64 | * `aux-build:foo.rs` - Compiles an auxiliary library for use in multi-crate tests. See the section on multi-crate testing below. 65 | * `exec-env:NAME` or `exec-env:NAME=VALUE` - Sets an environment variable during test execution 66 | * `debugger:CMD` - Issues a command to the debugger in `debuginfo` mode 67 | * `check:RESULT` - Checks the result of a previous `debugger:` directive in `debuginfo` mode 68 | 69 | There are eight directories containing compile tests, living in the src/tests directory: 70 | 71 | * run-pass - Tests that are expected to compile and run successfully. Also used for pretty-print testing. 72 | * run-pass-valgrind - Tests that are expected to compile and run successfully under Valgrind. Also used for pretty-print testing. 73 | * run-fail - Tests that are expected compile but fail when run. Also used for pretty-print testing. 74 | * compile-fail - Tests that are expected not to compile 75 | * bench - Benchmarks and miscellaneous snippets of code that are expected to compile and run successfully. Also used for pretty-print testing. 76 | * pretty - Pretty-print tests 77 | * debug-info - Debuginfo tests 78 | * codegen - Codegen tests 79 | * auxiliary - libraries used in multi-crate testing. See the section on this topic below. 80 | 81 | And finally, build targets: 82 | 83 | * `check-stage[N]-rpass` - The tests in the run-pass directory, in run-pass mode 84 | * `check-stage[N]-rpass-valgrind` - The tests in the run-pass-valgrind directory, in run-pass-valgrind mode 85 | * `check-stage[N]-rfail` - The tests in the run-fail-directory, in run-fail mode 86 | * `check-stage[N]-cfail` - The tests in the compile-fail directory, in compile-fail mode 87 | * `check-stage[N]-bench` - The tests in the bench directory, in run-pass mode 88 | * `check-stage[N]-pretty` - All the pretty-print tests 89 | * `check-stage[N]-pretty-rpass` - The tests in the run-pass directory, in pretty mode 90 | * `check-stage[N]-pretty-rpass-valgrind` - The tests in the run-pass-valgrind directory, in pretty mode 91 | * `check-stage[N]-pretty-rfail` - The tests in the run-fail directory, in pretty mode 92 | * `check-stage[N]-pretty-bench` - The tests in the bench directory, in pretty mode 93 | * `check-stage[N]-pretty-pretty` - The tests in the pretty directory, in pretty mode 94 | * `check-stage[N]-debuginfo` - The tests in the debuginfo directory 95 | * `check-stage[N]-codegen` - The tests in the codegen directory 96 | 97 | ### Specifying the expected errors and warnings 98 | 99 | When writing a compile-fail test, you must specify at least one 100 | expected error or warning message. The preferred way to do this is to 101 | place a comment with the form `//~ ERROR msg` or `//~ WARNING msg` on 102 | the line where the error or warning is expected to occur. You may 103 | have as many of these comments as you like. The test harness will 104 | verify that the compiler reports precisely the errors/warnings that are 105 | specified, no more and no less. An example of using the error/warning 106 | messages is: 107 | ```rust 108 | // Regression test for issue #XXX 109 | 110 | fn main() { 111 | let a: bool = 10; //~ ERROR mismatched types 112 | log (debug, b); 113 | } 114 | ``` 115 | In fact, this test would fail, because there are two errors: the type 116 | mismatch and the undefined variable `b`. 117 | 118 | Sometimes it is not possible or not convenient to place the `//~` 119 | comment on precisely the line where the error occurs. For those cases, 120 | you may make a comment of the form `//~^` where the caret `^` 121 | indicates that the error is expected to appear on the line above. You 122 | may have as many caret as you like, so `//~^^^ ERROR foo` indicates 123 | that the error message `foo` is expected to be reported 3 lines above 124 | the comment. We could therefore correct the above test like so: 125 | ```rust 126 | // Regression test for issue #XXX 127 | 128 | fn main() { 129 | let a: bool = 10; //~ ERROR mismatched types 130 | log (debug, b); 131 | //~^ ERROR undefined variable `b` 132 | } 133 | ``` 134 | 135 | The older technique for specifying error messages was to use an 136 | `error-pattern` directive. These directives are placed at the top of 137 | the file and each message found in an `error-pattern` directive must 138 | appear in the output. 139 | 140 | Using error comments is preferred, however, because it is a more 141 | thorough test: 142 | 143 | - It verifies that the error is reported on the expected line number. 144 | - It verifies that no additional errors or warnings are reported. 145 | 146 | ### Multi-crate testing 147 | 148 | Sometimes it is useful to write tests that make use of more than one crate. We have limited support for this scenario. Basically, you can write and add modules into the `src/test/auxiliary` directory. These files are not built nor tested directly. Instead, you write a main test in one of the other directories (`run-pass`, `compile-fail`, etc) and add a `aux-build` directive at the head of the main test. When running the main test, the test framework will build the files it is directed to build from the auxiliary directory. These builds *must* succeed or the test will fail. You can then include `use` and `import` commands to make use of the byproducts from these builds as you wish. 149 | 150 | An example consisting of two files: 151 | ```rust 152 | auxiliary/cci_iter_lib.rs: 153 | #[inline] 154 | fn iter(v: [T], f: fn(T)) {...} 155 | 156 | run-pass/cci_iter_exe.rs: 157 | // aux-build:cci_iter_lib.rs 158 | extern crate cci_iter_lib; 159 | fn main() { 160 | cci_iter_lib::iter([1, 2, 3]) {|i| ... } 161 | } 162 | ``` 163 | 164 | ### Recipes 165 | 166 | * Running the run-pass tests for stage1: `make check-stage1-rpass` 167 | * Running a specific compile-fail test: `make check-stage2-cfail TESTNAME=type-mismatch` 168 | * Finding the command to compile a failing test: `make check-stage1-rpass TESTNAME=hello VERBOSE=1` 169 | * Running ignored tests: `make check-stage1-rpass CHECK_IGNORED=1` 170 | 171 | ## Unit Tests 172 | 173 | Most crates include unit tests which are part of the crate they test. These crates are built with the `--test` flag and run as part of `make check`. 174 | 175 | `libcore` has its tests in a separate crate, named `libcoretest`. 176 | 177 | All tests in a module should go in an inner module named `test`, with the attribute `#[cfg(test)]`. Placing tests in their own module is a practical issue - because test cases are not included in normal builds, building with `--test` require a different set of imports than without, and that causes 'unused import' errors. 178 | 179 | ```rust 180 | use std::option; 181 | 182 | fn do_something() { ... } 183 | 184 | #[cfg(test)] 185 | mod test { 186 | use std::vec; 187 | 188 | fn helper_fn() { ... } 189 | 190 | #[test] 191 | fn resolve_fn_types() { 192 | ... 193 | } 194 | } 195 | ``` 196 | 197 | ### Build targets 198 | 199 | * `make check-stage[N]-crates` 200 | * `make check-stage[N]-[crate name]test` 201 | 202 | ## Documentation tests 203 | 204 | The build system is able to extract Rust code snippets from documentation and run them using the compiletest driver. Currently the tutorial and reference manual are tested this way. The targets are `make check-stage[N]-doc-tutorial` and `make check-stage[N]-doc-rust`, respectively. There are also several auxiliary guides; to run the tests extracted from them, do: 205 | 206 | * `make check-stage[N]-doc-guide-borrowed-ptr` 207 | * `make check-stage[N]-doc-guide-tasks` 208 | * `make check-stage[N]-doc-guide-ffi` 209 | * `make check-stage[N]-doc-guide-macros` 210 | * `make check-stage[N]-doc-guide-testing` 211 | 212 | Crate API docs are tested as well: 213 | 214 | * `make check-stage[N]-doc-crate-std` 215 | 216 | To run all doc tests use `make check-stage[N]-doc`. 217 | 218 | ## Minimal (but faster) checking on windows 219 | 220 | Because Windows has slow process spawning running `make check` on that platform can take a long time. For this reason we have a `make check-lite` target that the Windows build servers run to keep the cycle time down. This is a stripped-down target which only checks run-pass, run-fail, compile-fail, run-make and target libraries. 221 | 222 | ## Benchmarks, saved metrics and ratchets 223 | 224 | All benchmark metrics are saved by default. Depending on configuration, some benchmark metrics are ratcheted. The `codegen` compile tests are always ratcheted if they run, since they are deterministic / low-noise. See [[Doc unit testing]] for details on metrics and ratchets. 225 | -------------------------------------------------------------------------------- /Doc-building-for-android.md: -------------------------------------------------------------------------------- 1 | Rust has been ported to Android OS running on ARM architecture. Android on other architectures is not yet supported. 2 | 3 | **Important**: Right now, this only works correctly on linux. It can be made to work on OSX, but if you're on OSX, make things easy by setting up a VM. It has been successfully tested on ubuntu 14.04.2 in virtualbox, if you want something super safe, but most any debian-based thing will almost certainly work. 4 | 5 | In the issue tracker, [Android-related issues](https://github.com/rust-lang/rust/issues?labels=A-android) are labelled `A-android`, and [ARM-related issues](https://github.com/rust-lang/rust/issues?labels=A-ARM) are labelled `A-ARM`. 6 | 7 | Instructions to build a cross compiler to Android on ARM, to cross compile Rust sources, and to run resulting binaries follow. 8 | 9 | 1. Setup Android NDK standalone tool chain with your specific [API Level](http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels) 10 | 11 | Download android NDK version _r9b_ or later (you might not be able to build jemalloc with previous versions) from http://developer.android.com/tools/sdk/ndk/index.html. for example: 12 | 13 | $ wget http://dl.google.com/android/ndk/android-ndk-r10d-linux-x86_64.bin 14 | $ chmod +x android-ndk-r10d-linux-x86_64.bin 15 | $ ./android-ndk-r10d-linux-x86_64.bin 16 | $ ls android-ndk-r10d -d 17 | android-ndk-r10d 18 | 19 | example command to setup standalone tool chain: 20 | 21 | ~/android-ndk-/build/tools/make-standalone-toolchain.sh \ 22 | --platform=android-14 \ 23 | --arch=arm \ 24 | --install-dir=~/ndk-standalone-14-arm 25 | 26 | `--platform` indicates the Android API level - has successfully been tested with 18 as well 27 | `--install-dir` indicates the directory where the toolchain will be installed. You can pick 28 | more or less anything you feel like. 29 | `--arch` must be set to `arm`, or it won't know what toolchain to use. (Imagine that!) 30 | `--toolchain` can also be set to one of the names of the directories in 31 | `android-ndk-/toolchains/` - keeping in mind it must be one of the arm ones. 32 | Only do this if you know why you want to - otherwise, the default of ...-4.8 will work fine. 33 | 34 | If you're on 64bit linux, the android ndk needs 32bit linux libraries, such as `/lib32/libc.so.6`, `/usr/lib32/libz.so.1`, and `/usr/lib32/libstdc++.so.6.0.17`, so make sure they're installed. 35 | 36 | If you're using ubuntu 64, this command will do: 37 | 38 | apt-get install libc6-i386 lib32z1 lib32stdc++6 39 | 40 | Some of the tool chain will need to be placed in your path, if you plan to build with cargo. 41 | The easy way to do this is to add these environment variables in ~/.bashrc: 42 | 43 | export ANDROID_NDK=".../path/to/android-ndk-" 44 | export ANDROID_TOOLCHAIN=".../path/to/standalone/toolchain" 45 | export PATH="$PATH:$ANDROID_TOOLCHAIN/bin" 46 | 47 | For example: 48 | 49 | export ANDROID_NDK="$HOME/android-ndk-r10d" 50 | export ANDROID_TOOLCHAIN="$HOME/ndk-standalone-14-arm" 51 | export PATH="$PATH:$ANDROID_TOOLCHAIN/bin" 52 | 53 | Then do `source ~/.bashrc` to update your environment. 54 | 55 | 2. Download rustc from git repository 56 | 57 | git clone https://github.com/rust-lang/rust.git 58 | 59 | 3. Configure with ndk toolchain path 60 | 61 | mkdir build 62 | cd build 63 | 64 | ../configure \ 65 | --host=x86_64-unknown-linux-gnu \ 66 | --target=arm-linux-androideabi \ 67 | --android-cross-path="$ANDROID_TOOLCHAIN" 68 | 69 | 4. Build 70 | 71 | make 72 | 73 | make install 74 | 75 | `make install` will copy rustc binaries and libraries into /usr/local (or as defined with --prefix). You will probably need to do it as root, depending on whether you set --prefix when doing configure. 76 | 77 | 5. How to cross compile 78 | 79 | #### With rustc: 80 | 81 | rustc --target=arm-linux-androideabi \ 82 | -C linker=$ANDROID_TOOLCHAIN/bin/arm-linux-androideabi-gcc \ 83 | -C link-args=-pie \ 84 | hello.rs 85 | 86 | `-C link-args=-pie` is a workaround for [issue #17437](https://github.com/rust-lang/rust/issues/17437). 87 | 88 | #### With cargo: 89 | 90 | Because of the need for the `-C link-args=-pie` to rustc, a horrifying hack is required 91 | to build code for android using cargo: putting a `rustc` script earlier on PATH, that will 92 | add the `-C link-args=-pie` argument. This is because cargo doesn't allow us to directly 93 | set the link-args argument. This script will set up the workaround automatically: 94 | 95 | if [[ ! -d ~/bin ]]; then 96 | mkdir ~/bin 97 | fi 98 | # check if ~/bin comes before the location of rustc 99 | # and if it doesn't, put it there 100 | if [[ $PATH != *"$HOME/bin:"*"$(dirname $(which rustc))" ]]; then 101 | echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc 102 | fi 103 | 104 | cat > ~/bin/rustc << 105 | #!/bin/bash 106 | exec "$(which rustc)" -C link-args=-pie "\$@" 107 | END 108 | chmod +x ~/bin/rustc 109 | 110 | After running that script, make sure to `source ~/.bashrc` again, and then the 111 | following instructions should work. 112 | 113 | 1. Create a .cargo directory in your project's root dir 114 | 2. Create a config file inside the .cargo directory (proj/.cargo/config) 115 | 3. Place your deps/linker information inside that file. for example: 116 | 117 | [target.arm-linux-androideabi] 118 | linker = "arm-linux-androideabi-gcc" 119 | 120 | 4. Then, to compile: 121 | 122 | cargo build --target=arm-linux-androideabi 123 | 124 | 5. Copy `target/arm-linux-androideabi/` to your device, *not* `target/`. (This may change depending on how some cargo issues about the paths being confusing get resolved.) 125 | 126 | 6. How to run on Android 127 | 128 | 1. If necessary, get your binary off your VM or set up USB to pass through. How to do this varies a lot; if you copy the binary off your vm, you'll need the android sdk on your host, and adb set up in your host's PATH. 129 | 130 | 2. Push your binary 131 | 132 | $ adb push hello /data/local/tmp 133 | 134 | 3. Run using adb shell 135 | 136 | $ adb shell 137 | shell@hammerhead:/ $ cd /data/local/tmp 138 | shell@hammerhead:/ $ chmod 755 hello 139 | shell@hammerhead:/ $ ./hello 140 | it worked!! 141 | 142 | ...okay, hi. hello world. whatever. 143 | shell@hammerhead:/ $ exit 144 | $ 145 | 146 | ### How to add rust code into an ndk project to create an APK 147 | 148 | **Note: instructions beyond this point need further re-checking with latest android and rust.** 149 | 150 | Use rustc with --crate-type=staticlib etc to emit rust code which can be linked with C/C++ sources compiled by the android standalone toolchain's g++. From here is it possible to create an APK as with NDK examples. Use #[no_mangle] extern "C" rust functions to export functions which can be called by android frameworks 151 | 152 | Sample of modifications to the android-ndk "native-activity" sample makefile (jni/Android.mk) :- 153 | 154 | LOCAL_PATH := $(call my-dir) 155 | include $(CLEAR_VARS) 156 | 157 | LOCAL_MODULE := rust-prebuilt 158 | LOCAL_SRC_FILES := librust_android.a 159 | 160 | include $(PREBUILT_STATIC_LIBRARY) 161 | include $(CLEAR_VARS) 162 | 163 | LOCAL_MODULE := native-activity 164 | LOCAL_SRC_FILES := main.c 165 | LOCAL_LDLIBS := -llog -landroid -lEGL -lGLESv1_CM 166 | LOCAL_STATIC_LIBRARIES := android_native_app_glue rust-prebuilt 167 | 168 | include $(BUILD_SHARED_LIBRARY) 169 | 170 | $(call import-module,android/native_app_glue) 171 | 172 | This requires that you compiled rust code into a library beforehand, eg if 'hello_android.rs' is your crate root 173 | 174 | rustc --target=arm-linux-androideabi hello_android.rs --android-cross-path=/opt/ndk-standalone-arm/ --staticlib -o jni/librust_android.a 175 | 176 | execute ndk-build, ant debug|release etc to compile it into a native code .so and package,deploy it 177 | 178 | ### How to integrate as a Shared Library into Android Studio using NDK and Gradle 179 | 1. Edit your Cargo.toml to build as a dylib 180 | 181 | [lib] 182 | name = "my-awesome-lib" 183 | crate_type = ["dylib"] 184 | 2. Create a `jni` and `jniLibs` directory in your Android Studio project in `proj/app/src/main` 185 | 3. Copy your `libmy-awesome-lib-SOME_HASH.so` to `proj/app/src/main/jniLibs` without the hash extension cargo automagically generates 186 | 4. Place your C++ shim source in `proj/app/src/main/jni` 187 | 5. Since we have no headers to register symbols, you will need to register all of the `#[no_mangle] pub extern` Rust functions in your C++ shim before you call them. 188 | 189 | e.g.) 190 | 191 | Rust 192 | ----- 193 | #[no_mangle] 194 | pub extern an_int() -> c_int { 195 | 123 as c_int 196 | } 197 | 198 | C++ Shim 199 | --------- 200 | extern "C" { 201 | 202 | // Rust function prototypes 203 | int an_int(); 204 | 205 | jint 206 | Java_com_namespace_appname_MainActivity_callRustFunction(JNIEnv* env, jobject obj) 207 | { 208 | int some_int = an_int(); 209 | return some_int; 210 | } 211 | 212 | } // End extern 213 | 214 | 6. Android Studio will automatically include all `.so` files in `jniLibs` in the APK, but if you want to use a custom shim to wrap the Rust code in order to get the JNI name mangling correct, you will need a custom `Android.mk` with your shim source in your `jni` directory: 215 | 216 | LOCAL_PATH := $(call my-dir) 217 | 218 | include $(CLEAR_VARS) 219 | LOCAL_MODULE := my-awesome-lib 220 | LOCAL_SRC_FILES := ../jniLibs/$(TARGET_ARCH_ABI)/libmy-awesome-lib.so 221 | include $(PREBUILT_SHARED_LIBRARY) 222 | 223 | include $(CLEAR_VARS) 224 | LOCAL_MODULE := app-name 225 | LOCAL_SRC_FILES := shim.cpp 226 | LOCAL_SHARED_LIBRARIES := my-awesome-lib 227 | include $(BUILD_SHARED_LIBRARY) 228 | 7. By default, Android Studio generates a makefile in order to link against libs and headers included with the NDK and will generate one for all of your code in the `jni` directory. Unfortunately, this will not allow us to use ours, which includes our shared lib. A custom build.gradle will need created in order to manually build using `Android.mk` and copy the generated libs into the `jniLibs` directory. 229 | 230 | import org.apache.tools.ant.taskdefs.condition.Os 231 | 232 | def getPlatformNdkBuildCommand() { 233 | def rootDir = project.rootDir 234 | def localProperties = new File(rootDir, "local.properties") 235 | if (localProperties.exists()) { 236 | Properties properties = new Properties() 237 | localProperties.withInputStream { 238 | instr -> properties.load(instr) 239 | } 240 | def ndkDir = properties.getProperty('ndk.dir') 241 | if (ndkDir == null) { 242 | throw new GradleException("The ndk.dir property in local.propeties is not set") 243 | } 244 | def ndkBuild = Os.isFamily(Os.FAMILY_WINDOWS) ? "$ndkDir/ndk-build.cmd" : "$ndkDir/ndk-build" 245 | return ndkBuild 246 | } else { 247 | throw new GradleException("The local.properties file does not exist") 248 | } 249 | } 250 | 251 | apply plugin: 'com.android.application' 252 | 253 | android { 254 | compileSdkVersion 21 255 | buildToolsVersion "21.1.2" 256 | 257 | sourceSets.main { 258 | jniLibs.srcDir 'src/main/jniLibs' 259 | jni.srcDirs = [] //disable automatic ndk-build call 260 | } 261 | 262 | defaultConfig { 263 | applicationId "com.namespace.appname" 264 | minSdkVersion 15 265 | targetSdkVersion 21 266 | versionCode 1 267 | versionName "1.0" 268 | } 269 | 270 | buildTypes { 271 | release { 272 | minifyEnabled false 273 | proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro' 274 | } 275 | } 276 | 277 | // Compile cpp code from Android.mk 278 | task buildCppShim(type: Exec) { 279 | def ndkBuild = getPlatformNdkBuildCommand() 280 | commandLine "$ndkBuild", '-j8', '-C', file('src/main/jni').absolutePath 281 | } 282 | 283 | // Copy shared libs into jniLibs folder (Hacky workaround) 284 | task copySharedLibs(type: Copy) { 285 | from 'src/main/libs' 286 | into 'src/main/jniLibs' 287 | } 288 | 289 | tasks.withType(JavaCompile) { 290 | compileTask -> compileTask.dependsOn buildCppShim 291 | } 292 | 293 | copySharedLibs.dependsOn buildCppShim 294 | copySharedLibs.execute() 295 | } 296 | 297 | dependencies { 298 | compile fileTree(dir: 'lib', include: ['*.jar']) 299 | compile 'com.android.support:appcompat-v7:21.0.3' 300 | } 301 | 8. Add the location of the NDK to your `local.properties` file 302 | 303 | ndk.dir=/abs/path/to/extracted/android-ndk-r10d 304 | 9. Load the libraries in your Activity 305 | 306 | static { 307 | System.loadLibrary("my-awesome-lib"); 308 | System.loadLibrary("cpp-shim"); 309 | } --------------------------------------------------------------------------------