rust-lang / rust

Empowering everyone to build reliable and efficient software.

Website | Getting started | Learn | Documentation | Contributing

This is the main source code repository for Rust. It contains the compiler, standard library, and documentation.

Why Rust?

• Performance: Fast and memory-efficient, suitable for critical services, embedded devices, and easily integrate with other languages.

• Reliability: Our rich type system and ownership model ensure memory and thread safety, reducing bugs at compile-time.

• Productivity: Comprehensive documentation, a compiler committed to providing great diagnostics, and advanced tooling including package manager and build tool (Cargo), auto-formatter (rustfmt), linter (Clippy) and editor support (rust-analyzer).

Quick Start

Read "Installation" from The Book.

Installing from Source

If you really want to install from source (though this is not recommended), see INSTALL.md.

Getting Help

See https://www.rust-lang.org/community for a list of chat platforms and forums.

Contributing

See CONTRIBUTING.md.

License

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

See LICENSE-APACHE, LICENSE-MIT, and COPYRIGHT for details.

Trademark

The Rust Foundation owns and protects the Rust and Cargo trademarks and logos (the "Rust Trademarks").

If you want to use these names or brands, please read the media guide.

Third-party logos may be subject to third-party copyrights and trademarks. See Licenses for details.

rust's Issues

Complete name-mangling rules for linkage

For linkage versioning to be "safe" we need to implement the remaining pieces of https://mail.mozilla.org/pipermail/rust-dev/2010-December/000164.html , including the meta parts.

We might also want to update the mangling rules to make symbols follow C++ mangler format (absent the type encoding part), just to give gdb more of a fighting chance. Especially since we're using foo::bar now, its parser might even figure out what we mean.

Implement buffer-growing send

The <+ operator doesn't even parse yet, much less function.

flesh out the syntactic extension system

A very basic version of the syntactic extension system is working but only supports a test extension "#shell". Add a few more to see how it feels (#if-#else-#endif, #include, #env, #file, #line, #pos, possibly #re, #html, #bit -matching patterns, maybe a simple macro system?)

For this to really work long-term we need to wait on the self-hosting compiler, but an experiment or two would be useful.

support non-init output slots on STMT_call

Currently Trans.trans_call takes an argument indicating whether it's an
initializing call, but it always behaves as though it's initializing, even if
the argument is false. This is because there's a bit of a subtlety involved in
refcounted values: the same referent may be used as both dst of the call and as
an arg, and we want to avoid having it drop before being pinned as an arg,
because the dst was dropped.

The existing code may have been born in the CoW era and may no longer represent
a real hazard if rearranged to just pin args first then drop dst; will need a
few careful tests to be sure the arrangement actually works.

(Alternatively: worst case, make a static pass that prohibits x = f(x) the same
way f(x,x) is to be prohibited if both slots are alias-mode.)

Add fast path to bypass upcall_require on crate cache hit.

We always do one upcall_import to access the crate-cache, even though on a cache hit the upcall is not doing anything more complex than a couple indexed-load-and-compare checks and a return.

This is not necessary: we can emit those load/compare checks as a fast(er) hit path that stays in the stub, and only upcall on miss.

Deferring for now because it's still not a big cost at the moment, and there's more work to do around the stubs anyways in terms of refcounting.

proper CFI and dwarf engine to use it

Currently we're using a sort of 'shadow stack' approach wherein each frame
self-identifies its metadata in a location easily found from ebp. This is not
optimal, long term: to keep the metadata tractable, it means we're doing
expensive stuff like zeroing frames and slots all the time, and never reusing
lexical scopes. Painful. We need to get to the point of emitting Dwarf CFI (or
at worst, something similarly instruction-accurate) so we can determine
liveness and layout of everything in a frame, given an (sp,pc) pair.

Of course, the runtime also needs to learn how to reflect on this information
well enough to provide it to the unwinder. So this part is a long, slow
process. Possibly this needs to be a tracking bug for several sub-bugs.

implement flush

Flush should either be a statement or a library call. Probably just a library call.

Perform proper refcounting on imported crate-cache entries.

The crate-cache entries (and thus 'use'd crates) currently possess the ability to be flushed and reloaded, but the import calls fail to perform the refcounts on either side of cross-crate calls, and there isno exposed way to ask the runtime to request a flush/reload.

This will require some unwinding work as well, to drop refcounts when unwinding across a cross-crate call. And closure work, for captured imports. And other stuff.

GC control word for mutable closures

Closures that bind mutable data must have a GC control word in their
representation.

libuv bindings in stdlib

The standard library will require very carefully arranged bindings to libuv (https://github.com/joyent/libuv), the async IO library we're going to be using. The current rust IO system is synchronous and stdio-based, which is not really ideal long term.

bind's glue function should tail-call its target

Currently the glue function for `bind' does a non-tail call to the target
function. It should do the same thing as a tail call.

alias legwork

The 'alias' semantic analysis pass for marking slots as aliased is currently
incomplete; doesn't handle a bunch of AST nodes. Finish it.

Task links, failure trapping.

Presently task failure just fails parent task. Need trap / link mechanism.

floating point support

Currently there is zero support for floating point past ... perhaps the lexer
and a few of the machine-types? The IL translator, register allocator and
instruction selectors, at very least, have no clue. Threading the type through
the compiler shouldn't be too brutal -- a little tedious -- but might not be
fruitful to go all the way on this backend, as it may not live long enough to
pay for itself (as with u64 and s64). Not sure.

595

support native C++ modules w/ thiscall

We want to bridge to C++ objects at some point. Avoiding, for the time being,
the misery of vtables: add support for first-class native modules (constructed
over an address value) that thiscall through to name-mangled C++ member
functions.

configure runtime ABI by platform

The current runtime ABI is pretty x86-specific (including hard-wired number of
callee-saves and such). Abstract this out somewhat.

move yield and join into standard library

these should not be statements.

communication-alt statements

The 'alt { ... }' is a 'simple' readiness-switch for sends/receives over
multiple channels/ports. Doesn't do heavyweight poll() or bind/unbind event
channels, just fixed number of send/receive options. Need to add this.

Pretty-printer legwork

The AST pretty-printer is incomplete in a few places. Finish it.

implement stack growth check

Stack growth using segmented stacks needs implementation. There's a GSoC student working on the LLVM side of it. We need to make sure our runtime provides the necessary parts as well and get this working on our tasks. Not sure what the scope of work for us is.

complete typestate constraint-to-key mapping

Every constraint in the typestate system has to be mapped to a unique Semant.constr_key (see the comment next to that type for an explanation of why it exists) before anything else in the typestate system gets underway. Presently only a subset of possible constraint forms are mapped; the rest
fault. Complete the set of mappings.

implement 'big' type

There's a BSD implementation (in C) in the rt directory. Wire it into the compiler and runtime.

Thread a session or semantic context through IL

The IL module doesn't take a session variable, so its logging and session-state
actions are limited and/or global. Fix this.

add dwarf sibling links

Looking something up in dwarf is currently linear in the size of the dwarf
tables. Adding sibling links can drop this to a much faster scan, as we have a
hierarchical module namespace to make use of.

(Worst case we can also add a DIE type for hashed child access or such, but
leave that for future optimization)

abstract common patterns in AST formatters

The AST formatting functions have a lot of duplication. Abstract out patterns
like fmt_sequence and fmt_bracketed.

type parameter inference

Currently if you have a function f[T](T t) you have to call it with explicit
type parameters, such as f[int](10) or f[char]('a'). This is not generally
necessary given the restricted set of contexts in which we permit type
parameters; the type inference system should be able to infer parameters.

Implement this.

propagate constraints during copying

Copying from one slot to another should add a copy of every constraint that
includes the RHS of the assignment to the copy postcondition (with the RHS
renamed, in the constraint, to the new LHS slot).

In other words:

let int x = 10;
let int y = 11;
check lt(x,y); // postcond = { lt(x,y) }
let int z = x; // postcond = { lt(x,y), lt(z,y) }

Unless some horrible complications arise that make this impossible, I believe
the current rules permit this propagation to work.

synthesize check and prove stmts for type-carried typestate constraints

A type can carry its own set of constraints. Example:

type ordered_pair = (int,int) : lt(*._0, *._1);

Implicitly, after every initialization of a slot s of type ordered_pair, there
should be a "check lt(s._0, s._1);", and after every copy statement there
should be a "prove lt(s._0, s._1)" statement, so that the implied constraints
become enforced at initialization time and preserved during writes.

This doesn't literally require adding statements -- though that's one approach
-- but it needs to mimic the effect one way or another. Currently such
constraints are simply ignored.

perform refcounts on exteriors in llvm

we currently drop exteriors, but don't incr them on copy in the llvm backend.

teach dwarf to find vregs

Current dwarf info only finds memory-resident slots. Need to convey mapping
between vregs and spill slots to dwarf, as well as live range of either.

permit imports in fn, iter, obj scope

Currently we only permit import in mod scopes. It probably makes sense to
permit this in fn, iter and obj scopes as well, it's harmless there and potentially
restricts visibility of the import. Might as well.

vec and str slicing

If v is a vec, v.(1,2) should produce a slice -- a new vec over the new range.
Likewise strs.

implement lambda blocks

Should produce an alias to a non-copyable, non-sendable (resource) type, capturing the environment but not escaping.

implement 'break' and 'cont' statements.

To break out of loops. Simple in the local loop case. Slightly complex when dealing with iterators.

elide calls to empty glue

There are a few glue algorithms where we do structural recursion to generate
calls into sub-glue functions for each slot in a structured value
unnecessarily. We can discriminate between those structured values that have
sub-structure (or dtors) and those that are simple leaves, and omit calls to
their glue in some cases. For example, Trans.drop_slot on a structure like
@(int,int) will call a helper to 'drop' the interior bits of the exterior
tuple, despite the fact that it has no interesting substructure that needs
processing. We should notice this and avoid emitting the call (the called glue
is empty anyway).

implement detached-send

The send operators currently always deep-copy when they hit thread boundaries.
They should handle a mode in which a singly-referenced value can be sent
without deep-copying. This could take the form of a 'detached(x)' predicate
with a 'detach x' statement, that must hold before sending; or could simply be
part of the operator definition (that it detaches any memory before sending,
along with dropping the sent slot).

Note that there may be multiply-references leaves within a value that require
detachment themselves, so detachment is a recursive predicate / operation.

record type inference failing

See testcase rec-auto.rs. Bug in the typechecker.

Permit use before import

The parser is a little fussy at the moment and requires you to put
import/export directives before use directives. This should be relaxed.

Walker legwork

The walker module doesn't walk every AST node (some aren't implemented or supported anywhere in the compiler yet). Finish it.

move more slots to vregs

Currently we have a force-to-memory treatment that's too aggressive (Alias pins
any slot that's ever aliased, at all). As well, layout won't move any
exteriors or alias slots into vregs. This is all far too strong; we have (in
the meantime) grown support for temporarily forcing an explicit spill from
trans, which makes us more able to vreg-ify word-sized values.

So .. exploit this fact and move more stuff to vregs.

Only form import stubs for referenced imports.

Currently we emit an import stub for every item in an imported module tree.
This is wasteful. Most imported items are never going to be referenced by most
compilation units that reference them; there's no need to form import stubs for
the unreferenced ones.

Fixing this is a matter of a small table in semant full of 'node->referenced'
flags noted while resolving.

Signal-trap table

OS signals currently don't get trapped properly, nor do we have a timer thread that interrupts a runaway task. Add such, using a flag to indicate a pending signal. Put a check at preemption points (fn entries and loop edges).

structured compare

There is presently no support for comparing structured values (equality-wise,
order-wise or otherwise). Setting aside, if we may, the thorny question of how
we spell the deep vs. shallow comparison operators, it would be nice if we
could get some structured-comparison operator working.

clean up exception use in backend

Some of the backend modules (asm, x86, ra, pe) use 'raise' or 'failwith' in a
way that escapes to the top level. This is undesirable; we have more structured
error handling in the middle-end, and can probably classify / manage such
errors a bit better. Though of course, nothing's ever "really" supposed to go
wrong in the backend...

add an IL type checker

The IL has enough type structure now that is only informally-enforced by trans
and x86 that a "full" typechecker would probably be worthwhile.

encode and decode predicates and constraints via dwarf

Currently nothing about the typestate system passes through the crate metadata
we emit for dwarf. Implement this.

typecheck missing returns

If we have a function that must return T, we don't presently notice when there
is no ret statement returning T. Notice this and complain!

Single-element vec / str append.

This might involve digging in the typechecker a bit; it'd be good for these to
work:

let vec[T] v = ...;
let T t = ...;
v += t;

and

let str s = "hi";
s += 'x';

At the moment both the typechecker and the backend prefer to think of operator

• as only applying to identical-typed values. Which is usually good. This is
  just an exceptional case that might be good to provide support for.

For the time being we can fake it using a single-element temporary vec or a
single-char string. It's just kinda lame. But this is a lower-priority bug.

Classify spill / vreg address roles

Spills and vregs need to be classified as permanently address-holding or not-address-holding, and this has to be an exclusive feature of them. This is necessary to fix the horrible hack we're doing for stack-growth at the moment.