The Unstable Book

Welcome to the Unstable Book! This book consists of a number of chapters, each one organized by a "feature flag." That is, when using an unstable feature of Rust, you must use a flag, like this:

#![feature(box_syntax)]

fn main() {
    let five = box 5;
}

The box_syntax feature has a chapter describing how to use it.

Because this documentation relates to unstable features, we make no guarantees that what is contained here is accurate or up to date. It's developed on a best-effort basis. Each page will have a link to its tracking issue with the latest developments; you might want to check those as well.

abi_msp430_interrupt

The tracking issue for this feature is: #38487


abi_ptx

The tracking issue for this feature is: None.


abi_sysv64

The tracking issue for this feature is: #36167


abi_unadjusted

The tracking issue for this feature is: none.


abi_vectorcall

The tracking issue for this feature is: none.


abi_x86_interrupt

The tracking issue for this feature is: #40180


advanced_slice_patterns

The tracking issue for this feature is: #23121

See also slice_patterns.


The advanced_slice_patterns gate lets you use .. to indicate any number of elements inside a pattern matching a slice. This wildcard can only be used once for a given array. If there's an identifier before the .., the result of the slice will be bound to that name. For example:

#![feature(advanced_slice_patterns, slice_patterns)]

fn is_symmetric(list: &[u32]) -> bool {
    match list {
        &[] | &[_] => true,
        &[x, ref inside.., y] if x == y => is_symmetric(inside),
        _ => false
    }
}

fn main() {
    let sym = &[0, 1, 4, 2, 4, 1, 0];
    assert!(is_symmetric(sym));

    let not_sym = &[0, 1, 7, 2, 4, 1, 0];
    assert!(!is_symmetric(not_sym));
}

alloc_jemalloc

The tracking issue for this feature is: #33082

See also alloc_system.


The compiler currently ships two default allocators: alloc_system and alloc_jemalloc (some targets don't have jemalloc, however). These allocators are normal Rust crates and contain an implementation of the routines to allocate and deallocate memory. The standard library is not compiled assuming either one, and the compiler will decide which allocator is in use at compile-time depending on the type of output artifact being produced.

Binaries generated by the compiler will use alloc_jemalloc by default (where available). In this situation the compiler "controls the world" in the sense of it has power over the final link. Primarily this means that the allocator decision can be left up the compiler.

Dynamic and static libraries, however, will use alloc_system by default. Here Rust is typically a 'guest' in another application or another world where it cannot authoritatively decide what allocator is in use. As a result it resorts back to the standard APIs (e.g. malloc and free) for acquiring and releasing memory.

Switching Allocators

Although the compiler's default choices may work most of the time, it's often necessary to tweak certain aspects. Overriding the compiler's decision about which allocator is in use is done simply by linking to the desired allocator:

#![feature(alloc_system)]

extern crate alloc_system;

fn main() {
    let a = Box::new(4); // Allocates from the system allocator.
    println!("{}", a);
}

In this example the binary generated will not link to jemalloc by default but instead use the system allocator. Conversely to generate a dynamic library which uses jemalloc by default one would write:

#![feature(alloc_jemalloc)]
#![crate_type = "dylib"]

extern crate alloc_jemalloc;

pub fn foo() {
    let a = Box::new(4); // Allocates from jemalloc.
    println!("{}", a);
}
# fn main() {}

alloc_system

The tracking issue for this feature is: #33082

See also alloc_jemalloc.


The compiler currently ships two default allocators: alloc_system and alloc_jemalloc (some targets don't have jemalloc, however). These allocators are normal Rust crates and contain an implementation of the routines to allocate and deallocate memory. The standard library is not compiled assuming either one, and the compiler will decide which allocator is in use at compile-time depending on the type of output artifact being produced.

Binaries generated by the compiler will use alloc_jemalloc by default (where available). In this situation the compiler "controls the world" in the sense of it has power over the final link. Primarily this means that the allocator decision can be left up the compiler.

Dynamic and static libraries, however, will use alloc_system by default. Here Rust is typically a 'guest' in another application or another world where it cannot authoritatively decide what allocator is in use. As a result it resorts back to the standard APIs (e.g. malloc and free) for acquiring and releasing memory.

Switching Allocators

Although the compiler's default choices may work most of the time, it's often necessary to tweak certain aspects. Overriding the compiler's decision about which allocator is in use is done simply by linking to the desired allocator:

#![feature(alloc_system)]

extern crate alloc_system;

fn main() {
    let a = Box::new(4); // Allocates from the system allocator.
    println!("{}", a);
}

In this example the binary generated will not link to jemalloc by default but instead use the system allocator. Conversely to generate a dynamic library which uses jemalloc by default one would write:

#![feature(alloc_jemalloc)]
#![crate_type = "dylib"]

extern crate alloc_jemalloc;

pub fn foo() {
    let a = Box::new(4); // Allocates from jemalloc.
    println!("{}", a);
}
# fn main() {}

allocator

The tracking issue for this feature is: #27389


Sometimes even the choices of jemalloc vs the system allocator aren't enough and an entirely new custom allocator is required. In this you'll write your own crate which implements the allocator API (e.g. the same as alloc_system or alloc_jemalloc). As an example, let's take a look at a simplified and annotated version of alloc_system

# // Only needed for rustdoc --test down below.
# #![feature(lang_items)]
// The compiler needs to be instructed that this crate is an allocator in order
// to realize that when this is linked in another allocator like jemalloc should
// not be linked in.
#![feature(allocator)]
#![allocator]

// Allocators are not allowed to depend on the standard library which in turn
// requires an allocator in order to avoid circular dependencies. This crate,
// however, can use all of libcore.
#![no_std]

// Let's give a unique name to our custom allocator:
#![crate_name = "my_allocator"]
#![crate_type = "rlib"]

// Our system allocator will use the in-tree libc crate for FFI bindings. Note
// that currently the external (crates.io) libc cannot be used because it links
// to the standard library (e.g. `#![no_std]` isn't stable yet), so that's why
// this specifically requires the in-tree version.
#![feature(libc)]
extern crate libc;

// Listed below are the five allocation functions currently required by custom
// allocators. Their signatures and symbol names are not currently typechecked
// by the compiler, but this is a future extension and are required to match
// what is found below.
//
// Note that the standard `malloc` and `realloc` functions do not provide a way
// to communicate alignment so this implementation would need to be improved
// with respect to alignment in that aspect.

#[no_mangle]
pub extern fn __rust_allocate(size: usize, _align: usize) -> *mut u8 {
    unsafe { libc::malloc(size as libc::size_t) as *mut u8 }
}

#[no_mangle]
pub extern fn __rust_deallocate(ptr: *mut u8, _old_size: usize, _align: usize) {
    unsafe { libc::free(ptr as *mut libc::c_void) }
}

#[no_mangle]
pub extern fn __rust_reallocate(ptr: *mut u8, _old_size: usize, size: usize,
                                _align: usize) -> *mut u8 {
    unsafe {
        libc::realloc(ptr as *mut libc::c_void, size as libc::size_t) as *mut u8
    }
}

#[no_mangle]
pub extern fn __rust_reallocate_inplace(_ptr: *mut u8, old_size: usize,
                                        _size: usize, _align: usize) -> usize {
    old_size // This api is not supported by libc.
}

#[no_mangle]
pub extern fn __rust_usable_size(size: usize, _align: usize) -> usize {
    size
}

# // Only needed to get rustdoc to test this:
# fn main() {}
# #[lang = "panic_fmt"] fn panic_fmt() {}
# #[lang = "eh_personality"] fn eh_personality() {}
# #[lang = "eh_unwind_resume"] extern fn eh_unwind_resume() {}
# #[no_mangle] pub extern fn rust_eh_register_frames () {}
# #[no_mangle] pub extern fn rust_eh_unregister_frames () {}

After we compile this crate, it can be used as follows:

extern crate my_allocator;

fn main() {
    let a = Box::new(8); // Allocates memory via our custom allocator crate.
    println!("{}", a);
}

Custom allocator limitations

There are a few restrictions when working with custom allocators which may cause compiler errors:

  • Any one artifact may only be linked to at most one allocator. Binaries, dylibs, and staticlibs must link to exactly one allocator, and if none have been explicitly chosen the compiler will choose one. On the other hand rlibs do not need to link to an allocator (but still can).

  • A consumer of an allocator is tagged with #![needs_allocator] (e.g. the liballoc crate currently) and an #[allocator] crate cannot transitively depend on a crate which needs an allocator (e.g. circular dependencies are not allowed). This basically means that allocators must restrict themselves to libcore currently.

allow_internal_unstable

The tracking issue for this feature is: None.


asm

The tracking issue for this feature is: #29722


For extremely low-level manipulations and performance reasons, one might wish to control the CPU directly. Rust supports using inline assembly to do this via the asm! macro.

asm!(assembly template
   : output operands
   : input operands
   : clobbers
   : options
   );

Any use of asm is feature gated (requires #![feature(asm)] on the crate to allow) and of course requires an unsafe block.

Note: the examples here are given in x86/x86-64 assembly, but all platforms are supported.

Assembly template

The assembly template is the only required parameter and must be a literal string (i.e. "")

#![feature(asm)]

#[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
fn foo() {
    unsafe {
        asm!("NOP");
    }
}

// Other platforms:
#[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))]
fn foo() { /* ... */ }

fn main() {
    // ...
    foo();
    // ...
}

(The feature(asm) and #[cfg]s are omitted from now on.)

Output operands, input operands, clobbers and options are all optional but you must add the right number of : if you skip them:

# #![feature(asm)]
# #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
# fn main() { unsafe {
asm!("xor %eax, %eax"
    :
    :
    : "eax"
   );
# } }
# #[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))]
# fn main() {}

Whitespace also doesn't matter:

# #![feature(asm)]
# #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
# fn main() { unsafe {
asm!("xor %eax, %eax" ::: "eax");
# } }
# #[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))]
# fn main() {}

Operands

Input and output operands follow the same format: : "constraints1"(expr1), "constraints2"(expr2), ...". Output operand expressions must be mutable lvalues, or not yet assigned:

# #![feature(asm)]
# #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
fn add(a: i32, b: i32) -> i32 {
    let c: i32;
    unsafe {
        asm!("add $2, $0"
             : "=r"(c)
             : "0"(a), "r"(b)
             );
    }
    c
}
# #[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))]
# fn add(a: i32, b: i32) -> i32 { a + b }

fn main() {
    assert_eq!(add(3, 14159), 14162)
}

If you would like to use real operands in this position, however, you are required to put curly braces {} around the register that you want, and you are required to put the specific size of the operand. This is useful for very low level programming, where which register you use is important:

# #![allow(unused_variables)]
# 
#fn main() {
# #![feature(asm)]
# #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
# unsafe fn read_byte_in(port: u16) -> u8 {
let result: u8;
asm!("in %dx, %al" : "={al}"(result) : "{dx}"(port));
result
# }

#}

Clobbers

Some instructions modify registers which might otherwise have held different values so we use the clobbers list to indicate to the compiler not to assume any values loaded into those registers will stay valid.

# #![feature(asm)]
# #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
# fn main() { unsafe {
// Put the value 0x200 in eax:
asm!("mov $$0x200, %eax" : /* no outputs */ : /* no inputs */ : "eax");
# } }
# #[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))]
# fn main() {}

Input and output registers need not be listed since that information is already communicated by the given constraints. Otherwise, any other registers used either implicitly or explicitly should be listed.

If the assembly changes the condition code register cc should be specified as one of the clobbers. Similarly, if the assembly modifies memory, memory should also be specified.

Options

The last section, options is specific to Rust. The format is comma separated literal strings (i.e. :"foo", "bar", "baz"). It's used to specify some extra info about the inline assembly:

Current valid options are:

  1. volatile - specifying this is analogous to __asm__ __volatile__ (...) in gcc/clang.
  2. alignstack - certain instructions expect the stack to be aligned a certain way (i.e. SSE) and specifying this indicates to the compiler to insert its usual stack alignment code
  3. intel - use intel syntax instead of the default AT&T.
# #![feature(asm)]
# #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
# fn main() {
let result: i32;
unsafe {
   asm!("mov eax, 2" : "={eax}"(result) : : : "intel")
}
println!("eax is currently {}", result);
# }
# #[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))]
# fn main() {}

More Information

The current implementation of the asm! macro is a direct binding to LLVM's inline assembler expressions, so be sure to check out their documentation as well for more information about clobbers, constraints, etc.

associated_consts

The tracking issue for this feature is: #29646


With the associated_consts feature, you can define constants like this:

#![feature(associated_consts)]

trait Foo {
    const ID: i32;
}

impl Foo for i32 {
    const ID: i32 = 1;
}

fn main() {
    assert_eq!(1, i32::ID);
}

Any implementor of Foo will have to define ID. Without the definition:

#![feature(associated_consts)]

trait Foo {
    const ID: i32;
}

impl Foo for i32 {
}

gives

error: not all trait items implemented, missing: `ID` [E0046]
     impl Foo for i32 {
     }

A default value can be implemented as well:

#![feature(associated_consts)]

trait Foo {
    const ID: i32 = 1;
}

impl Foo for i32 {
}

impl Foo for i64 {
    const ID: i32 = 5;
}

fn main() {
    assert_eq!(1, i32::ID);
    assert_eq!(5, i64::ID);
}

As you can see, when implementing Foo, you can leave it unimplemented, as with i32. It will then use the default value. But, as in i64, we can also add our own definition.

Associated constants don’t have to be associated with a trait. An impl block for a struct or an enum works fine too:

# #![allow(unused_variables)]
# 
#fn main() {
#![feature(associated_consts)]

struct Foo;

impl Foo {
    const FOO: u32 = 3;
}

#}

associated_type_defaults

The tracking issue for this feature is: #29661


attr_literals

The tracking issue for this feature is: #34981


box_patterns

The tracking issue for this feature is: #29641

See also box_syntax


Box patterns let you match on Box<T>s:

#![feature(box_patterns)]

fn main() {
    let b = Some(Box::new(5));
    match b {
        Some(box n) if n < 0 => {
            println!("Box contains negative number {}", n);
        },
        Some(box n) if n >= 0 => {
            println!("Box contains non-negative number {}", n);
        },
        None => {
            println!("No box");
        },
        _ => unreachable!()
    }
}

box_syntax

The tracking issue for this feature is: #27779

See also box_patterns


Currently the only stable way to create a Box is via the Box::new method. Also it is not possible in stable Rust to destructure a Box in a match pattern. The unstable box keyword can be used to create a Box. An example usage would be:

#![feature(box_syntax)]

fn main() {
    let b = box 5;
}

cfg_target_feature

The tracking issue for this feature is: #29717


cfg_target_has_atomic

The tracking issue for this feature is: #32976


cfg_target_thread_local

The tracking issue for this feature is: #29594


cfg_target_feature

The tracking issue for this feature is: #29717


compiler_builtins

The tracking issue for this feature is: None.


concat_idents

The tracking issue for this feature is: #29599


conservative_impl_trait

The tracking issue for this feature is: #34511


const_fn

The tracking issue for this feature is: #24111


const_indexing

The tracking issue for this feature is: #29947


custom_attribute

The tracking issue for this feature is: #29642


custom_derive

The tracking issue for this feature is: #29644


default_type_parameter_fallback

The tracking issue for this feature is: #27336


drop_types_in_const

The tracking issue for this feature is: #33156


dropck_eyepatch

The tracking issue for this feature is: #34761


dropck_parametricity

The tracking issue for this feature is: #28498


exclusive_range_pattern

The tracking issue for this feature is: #37854


field_init_shorthand

The tracking issue for this feature is: #37340


fundamental

The tracking issue for this feature is: #29635


generic_param_attrs

The tracking issue for this feature is: #34761


i128_type

The tracking issue for this feature is: #35118


inclusive_range_syntax

The tracking issue for this feature is: #28237


intrinsics

The tracking issue for this feature is: None.

Intrinsics are never intended to be stable directly, but intrinsics are often exported in some sort of stable manner. Prefer using the stable interfaces to the intrinsic directly when you can.


These are imported as if they were FFI functions, with the special rust-intrinsic ABI. For example, if one was in a freestanding context, but wished to be able to transmute between types, and perform efficient pointer arithmetic, one would import those functions via a declaration like

#![feature(intrinsics)]
# fn main() {}

extern "rust-intrinsic" {
    fn transmute<T, U>(x: T) -> U;

    fn offset<T>(dst: *const T, offset: isize) -> *const T;
}

As with any other FFI functions, these are always unsafe to call.

lang_items

The tracking issue for this feature is: None.


The rustc compiler has certain pluggable operations, that is, functionality that isn't hard-coded into the language, but is implemented in libraries, with a special marker to tell the compiler it exists. The marker is the attribute #[lang = "..."] and there are various different values of ..., i.e. various different 'lang items'.

For example, Box pointers require two lang items, one for allocation and one for deallocation. A freestanding program that uses the Box sugar for dynamic allocations via malloc and free:

#![feature(lang_items, box_syntax, start, libc, core_intrinsics)]
#![no_std]
use core::intrinsics;

extern crate libc;

#[lang = "owned_box"]
pub struct Box<T>(*mut T);

#[lang = "exchange_malloc"]
unsafe fn allocate(size: usize, _align: usize) -> *mut u8 {
    let p = libc::malloc(size as libc::size_t) as *mut u8;

    // Check if `malloc` failed:
    if p as usize == 0 {
        intrinsics::abort();
    }

    p
}

#[lang = "exchange_free"]
unsafe fn deallocate(ptr: *mut u8, _size: usize, _align: usize) {
    libc::free(ptr as *mut libc::c_void)
}

#[lang = "box_free"]
unsafe fn box_free<T: ?Sized>(ptr: *mut T) {
    deallocate(ptr as *mut u8, ::core::mem::size_of_val(&*ptr), ::core::mem::align_of_val(&*ptr));
}

#[start]
fn main(argc: isize, argv: *const *const u8) -> isize {
    let x = box 1;

    0
}

#[lang = "eh_personality"] extern fn rust_eh_personality() {}
#[lang = "panic_fmt"] extern fn rust_begin_panic() -> ! { unsafe { intrinsics::abort() } }
# #[lang = "eh_unwind_resume"] extern fn rust_eh_unwind_resume() {}
# #[no_mangle] pub extern fn rust_eh_register_frames () {}
# #[no_mangle] pub extern fn rust_eh_unregister_frames () {}

Note the use of abort: the exchange_malloc lang item is assumed to return a valid pointer, and so needs to do the check internally.

Other features provided by lang items include:

  • overloadable operators via traits: the traits corresponding to the ==, <, dereferencing (*) and + (etc.) operators are all marked with lang items; those specific four are eq, ord, deref, and add respectively.
  • stack unwinding and general failure; the eh_personality, eh_unwind_resume, fail and fail_bounds_checks lang items.
  • the traits in std::marker used to indicate types of various kinds; lang items send, sync and copy.
  • the marker types and variance indicators found in std::marker; lang items covariant_type, contravariant_lifetime, etc.

Lang items are loaded lazily by the compiler; e.g. if one never uses Box then there is no need to define functions for exchange_malloc and exchange_free. rustc will emit an error when an item is needed but not found in the current crate or any that it depends on.

Most lang items are defined by libcore, but if you're trying to build an executable without the standard library, you'll run into the need for lang items. The rest of this page focuses on this use-case, even though lang items are a bit broader than that.

Using libc

In order to build a #[no_std] executable we will need libc as a dependency. We can specify this using our Cargo.toml file:

[dependencies]
libc = { version = "0.2.14", default-features = false }

Note that the default features have been disabled. This is a critical step - the default features of libc include the standard library and so must be disabled.

Writing an executable without stdlib

Controlling the entry point is possible in two ways: the #[start] attribute, or overriding the default shim for the C main function with your own.

The function marked #[start] is passed the command line parameters in the same format as C:

#![feature(lang_items, core_intrinsics)]
#![feature(start)]
#![no_std]
use core::intrinsics;

// Pull in the system libc library for what crt0.o likely requires.
extern crate libc;

// Entry point for this program.
#[start]
fn start(_argc: isize, _argv: *const *const u8) -> isize {
    0
}

// These functions are used by the compiler, but not
// for a bare-bones hello world. These are normally
// provided by libstd.
#[lang = "eh_personality"]
#[no_mangle]
pub extern fn rust_eh_personality() {
}

// This function may be needed based on the compilation target.
#[lang = "eh_unwind_resume"]
#[no_mangle]
pub extern fn rust_eh_unwind_resume() {
}

#[lang = "panic_fmt"]
#[no_mangle]
pub extern fn rust_begin_panic(_msg: core::fmt::Arguments,
                               _file: &'static str,
                               _line: u32) -> ! {
    unsafe { intrinsics::abort() }
}

To override the compiler-inserted main shim, one has to disable it with #![no_main] and then create the appropriate symbol with the correct ABI and the correct name, which requires overriding the compiler's name mangling too:

#![feature(lang_items, core_intrinsics)]
#![feature(start)]
#![no_std]
#![no_main]
use core::intrinsics;

// Pull in the system libc library for what crt0.o likely requires.
extern crate libc;

// Entry point for this program.
#[no_mangle] // ensure that this symbol is called `main` in the output
pub extern fn main(_argc: i32, _argv: *const *const u8) -> i32 {
    0
}

// These functions are used by the compiler, but not
// for a bare-bones hello world. These are normally
// provided by libstd.
#[lang = "eh_personality"]
#[no_mangle]
pub extern fn rust_eh_personality() {
}

// This function may be needed based on the compilation target.
#[lang = "eh_unwind_resume"]
#[no_mangle]
pub extern fn rust_eh_unwind_resume() {
}

#[lang = "panic_fmt"]
#[no_mangle]
pub extern fn rust_begin_panic(_msg: core::fmt::Arguments,
                               _file: &'static str,
                               _line: u32) -> ! {
    unsafe { intrinsics::abort() }
}

More about the language items

The compiler currently makes a few assumptions about symbols which are available in the executable to call. Normally these functions are provided by the standard library, but without it you must define your own. These symbols are called "language items", and they each have an internal name, and then a signature that an implementation must conform to.

The first of these functions, rust_eh_personality, is used by the failure mechanisms of the compiler. This is often mapped to GCC's personality function (see the libstd implementation for more information), but crates which do not trigger a panic can be assured that this function is never called. The language item's name is eh_personality.

The second function, rust_begin_panic, is also used by the failure mechanisms of the compiler. When a panic happens, this controls the message that's displayed on the screen. While the language item's name is panic_fmt, the symbol name is rust_begin_panic.

A third function, rust_eh_unwind_resume, is also needed if the custom_unwind_resume flag is set in the options of the compilation target. It allows customizing the process of resuming unwind at the end of the landing pads. The language item's name is eh_unwind_resume.

link_args

The tracking issue for this feature is: #29596


You can tell rustc how to customize linking, and that is via the link_args attribute. This attribute is applied to extern blocks and specifies raw flags which need to get passed to the linker when producing an artifact. An example usage would be:

#![feature(link_args)]

#[link_args = "-foo -bar -baz"]
extern {}
# fn main() {}

Note that this feature is currently hidden behind the feature(link_args) gate because this is not a sanctioned way of performing linking. Right now rustc shells out to the system linker (gcc on most systems, link.exe on MSVC), so it makes sense to provide extra command line arguments, but this will not always be the case. In the future rustc may use LLVM directly to link native libraries, in which case link_args will have no meaning. You can achieve the same effect as the link_args attribute with the -C link-args argument to rustc.

It is highly recommended to not use this attribute, and rather use the more formal #[link(...)] attribute on extern blocks instead.

link_cfg

The tracking issue for this feature is: #37406


link_llvm_intrinsics

The tracking issue for this feature is: #29602


linkage

The tracking issue for this feature is: #29603


log_syntax

The tracking issue for this feature is: #29598


loop_break_value

The tracking issue for this feature is: #37339


macro_reexport

The tracking issue for this feature is: #29638


main

The tracking issue for this feature is: #29634


naked_functions

The tracking issue for this feature is: #32408


needs_allocator

The tracking issue for this feature is: #27389


needs_panic_runtime

The tracking issue for this feature is: #32837


never_type

The tracking issue for this feature is: #35121


no_core

The tracking issue for this feature is: #29639


no_debug

The tracking issue for this feature is: #29721


non_ascii_idents

The tracking issue for this feature is: #28979


omit_gdb_pretty_printer_section

The tracking issue for this feature is: None.


on_unimplemented

The tracking issue for this feature is: #29628


optin_builtin_traits

The tracking issue for this feature is: #13231


panic_runtime

The tracking issue for this feature is: #32837


placement_in_syntax

The tracking issue for this feature is: #27779


platform_intrinsics

The tracking issue for this feature is: #27731


plugin

The tracking issue for this feature is: #29597

This feature is part of "compiler plugins." It will often be used with the plugin_registrar and rustc_private features.


rustc can load compiler plugins, which are user-provided libraries that extend the compiler's behavior with new syntax extensions, lint checks, etc.

A plugin is a dynamic library crate with a designated registrar function that registers extensions with rustc. Other crates can load these extensions using the crate attribute #![plugin(...)]. See the rustc_plugin documentation for more about the mechanics of defining and loading a plugin.

If present, arguments passed as #![plugin(foo(... args ...))] are not interpreted by rustc itself. They are provided to the plugin through the Registry's args method.

In the vast majority of cases, a plugin should only be used through #![plugin] and not through an extern crate item. Linking a plugin would pull in all of libsyntax and librustc as dependencies of your crate. This is generally unwanted unless you are building another plugin. The plugin_as_library lint checks these guidelines.

The usual practice is to put compiler plugins in their own crate, separate from any macro_rules! macros or ordinary Rust code meant to be used by consumers of a library.

Syntax extensions

Plugins can extend Rust's syntax in various ways. One kind of syntax extension is the procedural macro. These are invoked the same way as ordinary macros, but the expansion is performed by arbitrary Rust code that manipulates syntax trees at compile time.

Let's write a plugin roman_numerals.rs that implements Roman numeral integer literals.

#![crate_type="dylib"]
#![feature(plugin_registrar, rustc_private)]

extern crate syntax;
extern crate rustc;
extern crate rustc_plugin;

use syntax::parse::token;
use syntax::tokenstream::TokenTree;
use syntax::ext::base::{ExtCtxt, MacResult, DummyResult, MacEager};
use syntax::ext::build::AstBuilder;  // A trait for expr_usize.
use syntax::ext::quote::rt::Span;
use rustc_plugin::Registry;

fn expand_rn(cx: &mut ExtCtxt, sp: Span, args: &[TokenTree])
        -> Box<MacResult + 'static> {

    static NUMERALS: &'static [(&'static str, usize)] = &[
        ("M", 1000), ("CM", 900), ("D", 500), ("CD", 400),
        ("C",  100), ("XC",  90), ("L",  50), ("XL",  40),
        ("X",   10), ("IX",   9), ("V",   5), ("IV",   4),
        ("I",    1)];

    if args.len() != 1 {
        cx.span_err(
            sp,
            &format!("argument should be a single identifier, but got {} arguments", args.len()));
        return DummyResult::any(sp);
    }

    let text = match args[0] {
        TokenTree::Token(_, token::Ident(s)) => s.to_string(),
        _ => {
            cx.span_err(sp, "argument should be a single identifier");
            return DummyResult::any(sp);
        }
    };

    let mut text = &*text;
    let mut total = 0;
    while !text.is_empty() {
        match NUMERALS.iter().find(|&&(rn, _)| text.starts_with(rn)) {
            Some(&(rn, val)) => {
                total += val;
                text = &text[rn.len()..];
            }
            None => {
                cx.span_err(sp, "invalid Roman numeral");
                return DummyResult::any(sp);
            }
        }
    }

    MacEager::expr(cx.expr_usize(sp, total))
}

#[plugin_registrar]
pub fn plugin_registrar(reg: &mut Registry) {
    reg.register_macro("rn", expand_rn);
}

Then we can use rn!() like any other macro:

#![feature(plugin)]
#![plugin(roman_numerals)]

fn main() {
    assert_eq!(rn!(MMXV), 2015);
}

The advantages over a simple fn(&str) -> u32 are:

  • The (arbitrarily complex) conversion is done at compile time.
  • Input validation is also performed at compile time.
  • It can be extended to allow use in patterns, which effectively gives a way to define new literal syntax for any data type.

In addition to procedural macros, you can define new derive-like attributes and other kinds of extensions. See Registry::register_syntax_extension and the SyntaxExtension enum. For a more involved macro example, see regex_macros.

Tips and tricks

Some of the macro debugging tips are applicable.

You can use syntax::parse to turn token trees into higher-level syntax elements like expressions:

fn expand_foo(cx: &mut ExtCtxt, sp: Span, args: &[TokenTree])
        -> Box<MacResult+'static> {

    let mut parser = cx.new_parser_from_tts(args);

    let expr: P<Expr> = parser.parse_expr();

Looking through libsyntax parser code will give you a feel for how the parsing infrastructure works.

Keep the Spans of everything you parse, for better error reporting. You can wrap Spanned around your custom data structures.

Calling ExtCtxt::span_fatal will immediately abort compilation. It's better to instead call ExtCtxt::span_err and return DummyResult so that the compiler can continue and find further errors.

To print syntax fragments for debugging, you can use span_note together with syntax::print::pprust::*_to_string.

The example above produced an integer literal using AstBuilder::expr_usize. As an alternative to the AstBuilder trait, libsyntax provides a set of quasiquote macros. They are undocumented and very rough around the edges. However, the implementation may be a good starting point for an improved quasiquote as an ordinary plugin library.

Lint plugins

Plugins can extend Rust's lint infrastructure with additional checks for code style, safety, etc. Now let's write a plugin lint_plugin_test.rs that warns about any item named lintme.

#![feature(plugin_registrar)]
#![feature(box_syntax, rustc_private)]

extern crate syntax;

// Load rustc as a plugin to get macros
#[macro_use]
extern crate rustc;
extern crate rustc_plugin;

use rustc::lint::{EarlyContext, LintContext, LintPass, EarlyLintPass,
                  EarlyLintPassObject, LintArray};
use rustc_plugin::Registry;
use syntax::ast;

declare_lint!(TEST_LINT, Warn, "Warn about items named 'lintme'");

struct Pass;

impl LintPass for Pass {
    fn get_lints(&self) -> LintArray {
        lint_array!(TEST_LINT)
    }
}

impl EarlyLintPass for Pass {
    fn check_item(&mut self, cx: &EarlyContext, it: &ast::Item) {
        if it.ident.name.as_str() == "lintme" {
            cx.span_lint(TEST_LINT, it.span, "item is named 'lintme'");
        }
    }
}

#[plugin_registrar]
pub fn plugin_registrar(reg: &mut Registry) {
    reg.register_early_lint_pass(box Pass as EarlyLintPassObject);
}

Then code like

#![plugin(lint_plugin_test)]

fn lintme() { }

will produce a compiler warning:

foo.rs:4:1: 4:16 warning: item is named 'lintme', #[warn(test_lint)] on by default
foo.rs:4 fn lintme() { }
         ^~~~~~~~~~~~~~~

The components of a lint plugin are:

  • one or more declare_lint! invocations, which define static Lint structs;

  • a struct holding any state needed by the lint pass (here, none);

  • a LintPass implementation defining how to check each syntax element. A single LintPass may call span_lint for several different Lints, but should register them all through the get_lints method.

Lint passes are syntax traversals, but they run at a late stage of compilation where type information is available. rustc's built-in lints mostly use the same infrastructure as lint plugins, and provide examples of how to access type information.

Lints defined by plugins are controlled by the usual attributes and compiler flags, e.g. #[allow(test_lint)] or -A test-lint. These identifiers are derived from the first argument to declare_lint!, with appropriate case and punctuation conversion.

You can run rustc -W help foo.rs to see a list of lints known to rustc, including those provided by plugins loaded by foo.rs.

plugin_registrar

The tracking issue for this feature is: #29597

This feature is part of "compiler plugins." It will often be used with the plugin and rustc_private features as well. For more details, see their docs.


prelude_import

The tracking issue for this feature is: None.


proc_macro

The tracking issue for this feature is: #38356


pub_restricted

The tracking issue for this feature is: #32409


quote

The tracking issue for this feature is: #29601


relaxed_adts

The tracking issue for this feature is: #35626


repr_simd

The tracking issue for this feature is: #27731


rustc_attrs

The tracking issue for this feature is: #29642


rustc_diagnostic_macros

The tracking issue for this feature is: None.


sanitizer_runtime

The tracking issue for this feature is: None.


simd

The tracking issue for this feature is: #27731


simd_ffi

The tracking issue for this feature is: #27731


slice_patterns

The tracking issue for this feature is: #23121

See also advanced_slice_patterns.


If you want to match against a slice or array, you can use & with the slice_patterns feature:

#![feature(slice_patterns)]

fn main() {
    let v = vec!["match_this", "1"];

    match &v[..] {
        &["match_this", second] => println!("The second element is {}", second),
        _ => {},
    }
}

specialization

The tracking issue for this feature is: [#31844]


staged_api

The tracking issue for this feature is: None.


start

The tracking issue for this feature is: #29633


static_nobundle

The tracking issue for this feature is: #37403


static_recursion

The tracking issue for this feature is: #29719


stmt_expr_attributes

The tracking issue for this feature is: #15701


struct_field_attributes

The tracking issue for this feature is: #38814


structural_match

The tracking issue for this feature is: #31434


target_feature

The tracking issue for this feature is: None.


test

The tracking issue for this feature is: None.


The internals of the test crate are unstable, behind the test flag. The most widely used part of the test crate are benchmark tests, which can test the performance of your code. Let's make our src/lib.rs look like this (comments elided):

#![feature(test)]

extern crate test;

pub fn add_two(a: i32) -> i32 {
    a + 2
}

#[cfg(test)]
mod tests {
    use super::*;
    use test::Bencher;

    #[test]
    fn it_works() {
        assert_eq!(4, add_two(2));
    }

    #[bench]
    fn bench_add_two(b: &mut Bencher) {
        b.iter(|| add_two(2));
    }
}

Note the test feature gate, which enables this unstable feature.

We've imported the test crate, which contains our benchmarking support. We have a new function as well, with the bench attribute. Unlike regular tests, which take no arguments, benchmark tests take a &mut Bencher. This Bencher provides an iter method, which takes a closure. This closure contains the code we'd like to benchmark.

We can run benchmark tests with cargo bench:

$ cargo bench
   Compiling adder v0.0.1 (file:///home/steve/tmp/adder)
     Running target/release/adder-91b3e234d4ed382a

running 2 tests
test tests::it_works ... ignored
test tests::bench_add_two ... bench:         1 ns/iter (+/- 0)

test result: ok. 0 passed; 0 failed; 1 ignored; 1 measured

Our non-benchmark test was ignored. You may have noticed that cargo bench takes a bit longer than cargo test. This is because Rust runs our benchmark a number of times, and then takes the average. Because we're doing so little work in this example, we have a 1 ns/iter (+/- 0), but this would show the variance if there was one.

Advice on writing benchmarks:

  • Move setup code outside the iter loop; only put the part you want to measure inside
  • Make the code do "the same thing" on each iteration; do not accumulate or change state
  • Make the outer function idempotent too; the benchmark runner is likely to run it many times
  • Make the inner iter loop short and fast so benchmark runs are fast and the calibrator can adjust the run-length at fine resolution
  • Make the code in the iter loop do something simple, to assist in pinpointing performance improvements (or regressions)

Gotcha: optimizations

There's another tricky part to writing benchmarks: benchmarks compiled with optimizations activated can be dramatically changed by the optimizer so that the benchmark is no longer benchmarking what one expects. For example, the compiler might recognize that some calculation has no external effects and remove it entirely.

#![feature(test)]

extern crate test;
use test::Bencher;

#[bench]
fn bench_xor_1000_ints(b: &mut Bencher) {
    b.iter(|| {
        (0..1000).fold(0, |old, new| old ^ new);
    });
}

gives the following results

running 1 test
test bench_xor_1000_ints ... bench:         0 ns/iter (+/- 0)

test result: ok. 0 passed; 0 failed; 0 ignored; 1 measured

The benchmarking runner offers two ways to avoid this. Either, the closure that the iter method receives can return an arbitrary value which forces the optimizer to consider the result used and ensures it cannot remove the computation entirely. This could be done for the example above by adjusting the b.iter call to

# #![allow(unused_variables)]
# 
#fn main() {
# struct X;
# impl X { fn iter<T, F>(&self, _: F) where F: FnMut() -> T {} } let b = X;
b.iter(|| {
    // Note lack of `;` (could also use an explicit `return`).
    (0..1000).fold(0, |old, new| old ^ new)
});

#}

Or, the other option is to call the generic test::black_box function, which is an opaque "black box" to the optimizer and so forces it to consider any argument as used.

#![feature(test)]

extern crate test;

# fn main() {
# struct X;
# impl X { fn iter<T, F>(&self, _: F) where F: FnMut() -> T {} } let b = X;
b.iter(|| {
    let n = test::black_box(1000);

    (0..n).fold(0, |a, b| a ^ b)
})
# }

Neither of these read or modify the value, and are very cheap for small values. Larger values can be passed indirectly to reduce overhead (e.g. black_box(&huge_struct)).

Performing either of the above changes gives the following benchmarking results

running 1 test
test bench_xor_1000_ints ... bench:       131 ns/iter (+/- 3)

test result: ok. 0 passed; 0 failed; 0 ignored; 1 measured

However, the optimizer can still modify a testcase in an undesirable manner even when using either of the above.

thread_local

The tracking issue for this feature is: #29594


trace_macros

The tracking issue for this feature is: #29598


type_ascription

The tracking issue for this feature is: #23416


unboxed_closures

The tracking issue for this feature is: #29625


untagged_unions

The tracking issue for this feature is: #32836


unwind_attributes

The tracking issue for this feature is: None.


use_extern_macros

The tracking issue for this feature is: #35896


windows_subsystem

The tracking issue for this feature is: #37499