Welcome to "The rustc book"! rustc is the compiler for the Rust programming language, provided by the project itself. Compilers take your source code and produce binary code, either as a library or executable.

Most Rust programmers don't invoke rustc directly, but instead do it through Cargo. It's all in service of rustc though! If you want to see how Cargo calls rustc, you can

$ cargo build --verbose

And it will print out each rustc invocation. This book can help you understand what each of these options does. Additionally, while most Rustaceans use Cargo, not all do: sometimes they integrate rustc into other build systems. This book should provide a guide to all of the options you'd need to do so.

Let's say you've got a little hello world program in a file hello.rs:

fn main() {
    println!("Hello, world!");
}

To turn this source code into an executable, you can use rustc:

$ rustc hello.rs
$ ./hello # on a *NIX
$ .\hello.exe # on Windows

Note that we only ever pass rustc the crate root, not every file we wish to compile. For example, if we had a main.rs that looked like this:

mod foo;

fn main() {
    foo::hello();
}

And a foo.rs that had this:

pub fn hello() {
    println!("Hello, world!");
}

To compile this, we'd run this command:

$ rustc main.rs

No need to tell rustc about foo.rs; the mod statements give it everything that it needs. This is different than how you would use a C compiler, where you invoke the compiler on each file, and then link everything together. In other words, the crate is a translation unit, not a particular module.

Here's a list of command-line arguments to rustc and what they do.

This flag will print out help information for rustc.

This flag can turn on or off various #[cfg] settings.

The value can either be a single identifier or two identifiers separated by =.

For examples, --cfg 'verbose' or --cfg 'feature="serde"'. These correspond to #[cfg(verbose)] and #[cfg(feature = "serde")] respectively.

When looking for external crates or libraries, a directory passed to this flag will be searched.

The kind of search path can optionally be specified with the form -L KIND=PATH where KIND may be one of:

• dependency — Only search for transitive dependencies in this directory.
• crate — Only search for this crate's direct dependencies in this directory.
• native — Only search for native libraries in this directory.
• framework — Only search for macOS frameworks in this directory.
• all — Search for all library kinds in this directory. This is the default if KIND is not specified.

This flag allows you to specify linking to a specific native library when building a crate.

The kind of library can optionally be specified with the form -l KIND=lib where KIND may be one of:

• dylib — A native dynamic library.
• static — A native static library (such as a .a archive).
• framework — A macOS framework.

The kind of library can be specified in a #[link] attribute. If the kind is not specified in the link attribute or on the command-line, it will link a dynamic library if available, otherwise it will use a static library. If the kind is specified on the command-line, it will override the kind specified in a link attribute.

The name used in a link attribute may be overridden using the form -l ATTR_NAME:LINK_NAME where ATTR_NAME is the name in the link attribute, and LINK_NAME is the name of the actual library that will be linked.

This instructs rustc on which crate type to build. This flag accepts a comma-separated list of values, and may be specified multiple times. The valid crate types are:

• lib — Generates a library kind preferred by the compiler, currently defaults to rlib.
• rlib — A Rust static library.
• staticlib — A native static library.
• dylib — A Rust dynamic library.
• cdylib — A native dynamic library.
• bin — A runnable executable program.
• proc-macro — Generates a format suitable for a procedural macro library that may be loaded by the compiler.

The crate type may be specified with the crate_type attribute. The --crate-type command-line value will override the crate_type attribute.

More details may be found in the linkage chapter of the reference.

This informs rustc of the name of your crate.

This flag takes a value of 2015 or 2018. The default is 2015. More information about editions may be found in the edition guide.

This flag controls the types of output files generated by the compiler. It accepts a comma-separated list of values, and may be specified multiple times. The valid emit kinds are:

• asm — Generates a file with the crate's assembly code. The default output filename is CRATE_NAME.s.
• dep-info — Generates a file with Makefile syntax that indicates all the source files that were loaded to generate the crate. The default output filename is CRATE_NAME.d.
• link — Generates the crates specified by --crate-type. The default output filenames depend on the crate type and platform. This is the default if --emit is not specified.
• llvm-bc — Generates a binary file containing the LLVM bitcode. The default output filename is CRATE_NAME.bc.
• llvm-ir — Generates a file containing LLVM IR. The default output filename is CRATE_NAME.ll.
• metadata — Generates a file containing metadata about the crate. The default output filename is CRATE_NAME.rmeta.
• mir — Generates a file containing rustc's mid-level intermediate representation. The default output filename is CRATE_NAME.mir.
• obj — Generates a native object file. The default output filename is CRATE_NAME.o.

The output filename can be set with the -o flag. A suffix may be added to the filename with the -C extra-filename flag. The files are written to the current directory unless the --out-dir flag is used. Each emission type may also specify the output filename with the form KIND=PATH, which takes precedence over the -o flag.

This flag prints out various information about the compiler. This flag may be specified multiple times, and the information is printed in the order the flags are specified. Specifying a --print flag will usually disable the --emit step and will only print the requested information. The valid types of print values are:

• crate-name — The name of the crate.
• file-names — The names of the files created by the link emit kind.
• sysroot — Path to the sysroot.
• cfg — List of cfg values. See conditional compilation for more information about cfg values.
• target-list — List of known targets. The target may be selected with the --target flag.
• target-cpus — List of available CPU values for the current target. The target CPU may be selected with the -C target-cpu=val flag.
• target-features — List of available target features for the current target. Target features may be enabled with the -C target-feature=val flag.
• relocation-models — List of relocation models. Relocation models may be selected with the -C relocation-model=val flag.
• code-models — List of code models. Code models may be selected with the -C code-model=val flag.
• tls-models — List of Thread Local Storage models supported. The model may be selected with the -Z tls-model=val flag.
• native-static-libs — This may be used when creating a staticlib crate type. If this is the only flag, it will perform a full compilation and include a diagnostic note that indicates the linker flags to use when linking the resulting static library. The note starts with the text native-static-libs: to make it easier to fetch the output.

A synonym for -C debuginfo=2, for more see here.

A synonym for -C opt-level=2, for more see here.

This flag controls the output filename.

The outputted crate will be written to this directory. This flag is ignored if the -o flag is used.

Each error of rustc's comes with an error code; this will print out a longer explanation of a given error.

When compiling this crate, rustc will ignore your main function and instead produce a test harness.

This controls which target to produce.

This flag will set which lints should be set to the warn level.

This flag will set which lints should be set to the allow level.

This flag will set which lints should be set to the deny level.

This flag will set which lints should be set to the forbid level.

This flag will allow you to set unstable options of rustc. In order to set multiple options, the -Z flag can be used multiple times. For example: rustc -Z verbose -Z time. Specifying options with -Z is only available on nightly. To view all available options run: rustc -Z help.

This flag lets you 'cap' lints, for more, see here.

This flag will allow you to set codegen options.

This flag will print out rustc's version.

This flag, when combined with other flags, makes them produce extra output.

This flag allows you to pass the name and location of an external crate that will be linked into the crate you are building. This flag may be specified multiple times. The format of the value should be CRATENAME=PATH.

The "sysroot" is where rustc looks for the crates that come with the Rust distribution; this flag allows that to be overridden.

This flag lets you control the format of messages. Messages are printed to stderr. The valid options are:

• human — Human-readable output. This is the default.
• json — Structured JSON output.
• short — Short, one-line messages.

This flag lets you control color settings of the output. The valid options are:

• auto — Use colors if output goes to a tty. This is the default.
• always — Always use colors.
• never — Never colorize output.

Remap source path prefixes in all output, including compiler diagnostics, debug information, macro expansions, etc. It takes a value of the form FROM=TO where a path prefix equal to FROM is rewritten to the value TO. The FROM may itself contain an = symbol, but the TO value may not. This flag may be specified multiple times.

This is useful for normalizing build products, for example by removing the current directory out of pathnames emitted into the object files. The replacement is purely textual, with no consideration of the current system's pathname syntax. For example --remap-path-prefix foo=bar will match foo/lib.rs but not ./foo/lib.rs.

In software, a "lint" is a tool used to help improve your source code. The Rust compiler contains a number of lints, and when it compiles your code, it will also run the lints. These lints may produce a warning, an error, or nothing at all, depending on how you've configured things.

Here's a small example:

$ cat main.rs
fn main() {
    let x = 5;
}
$ rustc main.rs
warning: unused variable: `x`
 --> main.rs:2:9
  |
2 |     let x = 5;
  |         ^
  |
  = note: #[warn(unused_variables)] on by default
  = note: to avoid this warning, consider using `_x` instead

This is the unused_variables lint, and it tells you that you've introduced a variable that you don't use in your code. That's not wrong, so it's not an error, but it might be a bug, so you get a warning.

In rustc, lints are divided into four levels:

1. allow
2. warn
3. deny
4. forbid

Each lint has a default level (explained in the lint listing later in this chapter), and the compiler has a default warning level. First, let's explain what these levels mean, and then we'll talk about configuration.

These lints exist, but by default, do nothing. For example, consider this source:

# #![allow(unused_variables)]
#fn main() {
pub fn foo() {}
#}

Compiling this file produces no warnings:

$ rustc lib.rs --crate-type=lib
$

But this code violates the missing_docs lint.

These lints exist mostly to be manually turned on via configuration, as we'll talk about later in this section.

The 'warn' lint level will produce a warning if you violate the lint. For example, this code runs afoul of the unused_variable lint:

# #![allow(unused_variables)]
#fn main() {
pub fn foo() {
    let x = 5;
}
#}

This will produce this warning:

$ rustc lib.rs --crate-type=lib
warning: unused variable: `x`
 --> lib.rs:2:9
  |
2 |     let x = 5;
  |         ^
  |
  = note: #[warn(unused_variables)] on by default
  = note: to avoid this warning, consider using `_x` instead

A 'deny' lint produces an error if you violate it. For example, this code runs into the exceeding_bitshifts lint.

fn main() {
    100u8 << 10;
}

$ rustc main.rs
error: bitshift exceeds the type's number of bits
 --> main.rs:2:13
  |
2 |     100u8 << 10;
  |     ^^^^^^^^^^^
  |
  = note: #[deny(exceeding_bitshifts)] on by default

What's the difference between an error from a lint and a regular old error? Lints are configurable via levels, so in a similar way to 'allow' lints, warnings that are 'deny' by default let you allow them. Similarly, you may wish to set up a lint that is warn by default to produce an error instead. This lint level gives you that.

'forbid' is a special lint level that's stronger than 'deny'. It's the same as 'deny' in that a lint at this level will produce an error, but unlike the 'deny' level, the 'forbid' level can not be overridden to be anything lower than an error. However, lint levels may still be capped with --cap-lints (see below) so rustc --cap-lints warn will make lints set to 'forbid' just warn.

Remember our missing_docs example from the 'allow' lint level?

$ cat lib.rs
pub fn foo() {}
$ rustc lib.rs --crate-type=lib
$

We can configure this lint to operate at a higher level, both with compiler flags, as well as with an attribute in the source code.

You can also "cap" lints so that the compiler can choose to ignore certain lint levels. We'll talk about that last.

The -A, -W, -D, and -F flags let you turn one or more lints into allowed, warning, deny, or forbid levels, like this:

$ rustc lib.rs --crate-type=lib -W missing-docs
warning: missing documentation for crate
 --> lib.rs:1:1
  |
1 | pub fn foo() {}
  | ^^^^^^^^^^^^
  |
  = note: requested on the command line with `-W missing-docs`

warning: missing documentation for a function
 --> lib.rs:1:1
  |
1 | pub fn foo() {}
  | ^^^^^^^^^^^^

$ rustc lib.rs --crate-type=lib -D missing-docs
error: missing documentation for crate
 --> lib.rs:1:1
  |
1 | pub fn foo() {}
  | ^^^^^^^^^^^^
  |
  = note: requested on the command line with `-D missing-docs`

error: missing documentation for a function
 --> lib.rs:1:1
  |
1 | pub fn foo() {}
  | ^^^^^^^^^^^^

error: aborting due to 2 previous errors

You can also pass each flag more than once for changing multiple lints:

$ rustc lib.rs --crate-type=lib -D missing-docs -D unused-variables

And of course, you can mix these four flags together:

$ rustc lib.rs --crate-type=lib -D missing-docs -A unused-variables

You can also modify the lint level with a crate-wide attribute:

$ cat lib.rs
#![warn(missing_docs)]

pub fn foo() {}
$ rustc lib.rs --crate-type=lib
warning: missing documentation for crate
 --> lib.rs:1:1
  |
1 | / #![warn(missing_docs)]
2 | |
3 | | pub fn foo() {}
  | |_______________^
  |
note: lint level defined here
 --> lib.rs:1:9
  |
1 | #![warn(missing_docs)]
  |         ^^^^^^^^^^^^

warning: missing documentation for a function
 --> lib.rs:3:1
  |
3 | pub fn foo() {}
  | ^^^^^^^^^^^^

All four, warn, allow, deny, and forbid all work this way.

You can also pass in multiple lints per attribute:

# #![allow(unused_variables)]
#![warn(missing_docs, unused_variables)]

#fn main() {
pub fn foo() {}
#}

And use multiple attributes together:

# #![allow(unused_variables)]
#![warn(missing_docs)]
#![deny(unused_variables)]

#fn main() {
pub fn foo() {}
#}

rustc supports a flag, --cap-lints LEVEL that sets the "lint cap level." This is the maximum level for all lints. So for example, if we take our code sample from the "deny" lint level above:

fn main() {
    100u8 << 10;
}

And we compile it, capping lints to warn:

$ rustc lib.rs --cap-lints warn
warning: bitshift exceeds the type's number of bits
 --> lib.rs:2:5
  |
2 |     100u8 << 10;
  |     ^^^^^^^^^^^
  |
  = note: #[warn(exceeding_bitshifts)] on by default

warning: this expression will panic at run-time
 --> lib.rs:2:5
  |
2 |     100u8 << 10;
  |     ^^^^^^^^^^^ attempt to shift left with overflow

It now only warns, rather than errors. We can go further and allow all lints:

$ rustc lib.rs --cap-lints allow
$

This feature is used heavily by Cargo; it will pass --cap-lints allow when compiling your dependencies, so that if they have any warnings, they do not pollute the output of your build.

rustc has the concept of a "lint group", where you can toggle several warnings through one name.

For example, the nonstandard-style lint sets non-camel-case-types, non-snake-case, and non-upper-case-globals all at once. So these are equivalent:

$ rustc -D nonstandard-style
$ rustc -D non-camel-case-types -D non-snake-case -D non-upper-case-globals

Here's a list of each lint group, and the lints that they are made up of:

Additionally, there's a bad-style lint group that's a deprecated alias for nonstandard-style.

Finally, you can also see the table above by invoking rustc -W help. This will give you the exact values for the specific compiler you have installed.

This section lists out all of the lints, grouped by their default lint levels.

You can also see this list by running rustc -W help.

These lints are all set to the 'allow' level by default. As such, they won't show up unless you set them to a higher lint level with a flag or attribute.

This lint detects anonymous parameters. Some example code that triggers this lint:

# #![allow(unused_variables)]
#fn main() {
trait Foo {
    fn foo(usize);
}
#}

When set to 'deny', this will produce:

error: use of deprecated anonymous parameter
 --> src/lib.rs:5:11
  |
5 |     fn foo(usize);
  |           ^
  |
  = warning: this was previously accepted by the compiler but is being phased out; it will become a hard error in a future release!
  = note: for more information, see issue #41686 <https://github.com/rust-lang/rust/issues/41686>

This syntax is mostly a historical accident, and can be worked around quite easily:

# #![allow(unused_variables)]
#fn main() {
trait Foo {
    fn foo(_: usize);
}
#}

This lint suggests using dyn Trait for trait objects. Some example code that triggers this lint:

# #![allow(unused_variables)]
#![feature(dyn_trait)]

#fn main() {
trait Trait { }

fn takes_trait_object(_: Box<Trait>) {
}
#}

When set to 'deny', this will produce:

error: trait objects without an explicit `dyn` are deprecated
 --> src/lib.rs:7:30
  |
7 | fn takes_trait_object(_: Box<Trait>) {
  |                              ^^^^^ help: use `dyn`: `dyn Trait`
  |

To fix it, do as the help message suggests:

# #![allow(unused_variables)]
#![feature(dyn_trait)]
#![deny(bare_trait_objects)]

#fn main() {
trait Trait { }

fn takes_trait_object(_: Box<dyn Trait>) {
}
#}

This lints use of the Box type. Some example code that triggers this lint:

# #![allow(unused_variables)]
#fn main() {
struct Foo {
    x: Box<isize>,
}
#}

When set to 'deny', this will produce:

error: type uses owned (Box type) pointers: std::boxed::Box<isize>
 --> src/lib.rs:6:5
  |
6 |     x: Box<isize> //~ ERROR type uses owned
  |     ^^^^^^^^^^^^^
  |

This lint is mostly historical, and not particularly useful. Box<T> used to be built into the language, and the only way to do heap allocation. Today's Rust can call into other allocators, etc.

This lint detects the use of hidden lifetime parameters. Some example code that triggers this lint:

# #![allow(unused_variables)]
#fn main() {
struct Foo<'a> {
    x: &'a u32
}

fn foo(x: &Foo) {
}
#}

When set to 'deny', this will produce:

error: hidden lifetime parameters are deprecated, try `Foo<'_>`
 --> src/lib.rs:5:12
  |
5 | fn foo(x: &Foo) {
  |            ^^^
  |

Lifetime elision elides this lifetime, but that is being deprecated.

This lint detects potentially-forgotten implementations of Copy. Some example code that triggers this lint:

# #![allow(unused_variables)]
#fn main() {
pub struct Foo {
    pub field: i32
}
#}

When set to 'deny', this will produce:

error: type could implement `Copy`; consider adding `impl Copy`
 --> src/main.rs:3:1
  |
3 | / pub struct Foo { //~ ERROR type could implement `Copy`; consider adding `impl Copy`
4 | |     pub field: i32
5 | | }
  | |_^
  |

You can fix the lint by deriving Copy.

This lint is set to 'allow' because this code isn't bad; it's common to write newtypes like this specifically so that a Copy type is no longer Copy.

This lint detects missing implementations of fmt::Debug. Some example code that triggers this lint:

# #![allow(unused_variables)]
#fn main() {
pub struct Foo;
#}

When set to 'deny', this will produce:

error: type does not implement `fmt::Debug`; consider adding #[derive(Debug)] or a manual implementation
 --> src/main.rs:3:1
  |
3 | pub struct Foo;
  | ^^^^^^^^^^^^^^^
  |

You can fix the lint by deriving Debug.

This lint detects missing documentation for public items. Some example code that triggers this lint:

# #![allow(unused_variables)]
#fn main() {
pub fn foo() {}
#}

When set to 'deny', this will produce:

error: missing documentation for crate
 --> src/main.rs:1:1
  |
1 | / #![deny(missing_docs)]
2 | |
3 | | pub fn foo() {}
4 | |
5 | | fn main() {}
  | |____________^
  |

error: missing documentation for a function
 --> src/main.rs:3:1
  |
3 | pub fn foo() {}
  | ^^^^^^^^^^^^

To fix the lint, add documentation to all items.

This lint detects lifetimes that are only used once. Some example code that triggers this lint:

# #![allow(unused_variables)]
#fn main() {
struct Foo<'x> {
    x: &'x u32
}
#}

When set to 'deny', this will produce:

error: lifetime name `'x` only used once
 --> src/main.rs:3:12
  |
3 | struct Foo<'x> {
  |            ^^
  |

This lint detects trivial casts which could be removed. Some example code that triggers this lint:

# #![allow(unused_variables)]
#fn main() {
let x: &u32 = &42;
let _ = x as *const u32;
#}

When set to 'deny', this will produce:

error: trivial cast: `&u32` as `*const u32`. Cast can be replaced by coercion, this might require type ascription or a temporary variable
 --> src/main.rs:5:13
  |
5 |     let _ = x as *const u32;
  |             ^^^^^^^^^^^^^^^
  |
note: lint level defined here
 --> src/main.rs:1:9
  |
1 | #![deny(trivial_casts)]
  |         ^^^^^^^^^^^^^

This lint detects trivial casts of numeric types which could be removed. Some example code that triggers this lint:

# #![allow(unused_variables)]
#fn main() {
let x = 42i32 as i32;
#}

When set to 'deny', this will produce:

error: trivial numeric cast: `i32` as `i32`. Cast can be replaced by coercion, this might require type ascription or a temporary variable
 --> src/main.rs:4:13
  |
4 |     let x = 42i32 as i32;
  |             ^^^^^^^^^^^^
  |

This lint triggers for pub items not reachable from the crate root. Some example code that triggers this lint:

# #![allow(unused_variables)]
#fn main() {
mod foo {
    pub mod bar {
        
    }
}
#}

When set to 'deny', this will produce:

error: unreachable `pub` item
 --> src/main.rs:4:5
  |
4 |     pub mod bar {
  |     ---^^^^^^^^
  |     |
  |     help: consider restricting its visibility: `pub(crate)`
  |

This lint catches usage of unsafe code. Some example code that triggers this lint:

fn main() {
    unsafe {

    }
}

When set to 'deny', this will produce:

error: usage of an `unsafe` block
 --> src/main.rs:4:5
  |
4 | /     unsafe {
5 | |         
6 | |     }
  | |_____^
  |

This lint is deprecated and no longer used.

This lint guards against extern crate items that are never used. Some example code that triggers this lint:

extern crate semver;

When set to 'deny', this will produce:

error: unused extern crate
 --> src/main.rs:3:1
  |
3 | extern crate semver;
  | ^^^^^^^^^^^^^^^^^^^^
  |

This lint catches unnecessary braces around an imported item. Some example code that triggers this lint:

use test::{A};

pub mod test {
    pub struct A;
}
# fn main() {}

When set to 'deny', this will produce:

error: braces around A is unnecessary
 --> src/main.rs:3:1
  |
3 | use test::{A};
  | ^^^^^^^^^^^^^^
  |

To fix it, use test::A;

This lint detects unnecessarily qualified names. Some example code that triggers this lint:

mod foo {
    pub fn bar() {}
}

fn main() {
    use foo::bar;
    foo::bar();
}

When set to 'deny', this will produce:

error: unnecessary qualification
 --> src/main.rs:9:5
  |
9 |     foo::bar();
  |     ^^^^^^^^
  |

You can call bar() directly, without the foo::.

This lint checks for the unused result of an expression in a statement. Some example code that triggers this lint:

fn foo<T>() -> T { panic!() }

fn main() {
    foo::<usize>();
}

When set to 'deny', this will produce:

error: unused result
 --> src/main.rs:6:5
  |
6 |     foo::<usize>();
  |     ^^^^^^^^^^^^^^^
  |

This lint detects enums with widely varying variant sizes. Some example code that triggers this lint:

# #![allow(unused_variables)]
#fn main() {
enum En {
    V0(u8),
    VBig([u8; 1024]),
}
#}

When set to 'deny', this will produce:

error: enum variant is more than three times larger (1024 bytes) than the next largest
 --> src/main.rs:5:5
  |
5 |     VBig([u8; 1024]),   //~ ERROR variant is more than three times larger
  |     ^^^^^^^^^^^^^^^^
  |

These lints are all set to the 'warn' level by default.

This lint detects an erroneous expression while doing constant evaluation. Some example code that triggers this lint:

let b = 200u8 + 200u8;

This will produce:

warning: attempt to add with overflow
 --> src/main.rs:2:9
  |
2 | let b = 200u8 + 200u8;
  |         ^^^^^^^^^^^^^
  |

This lint detects unused, unexported items. Some example code that triggers this lint:

# #![allow(unused_variables)]
#fn main() {
fn foo() {}
#}

This will produce:

warning: function is never used: `foo`
 --> src/lib.rs:2:1
  |
2 | fn foo() {}
  | ^^^^^^^^
  |

This lint detects use of deprecated items. Some example code that triggers this lint:

# #![allow(unused_variables)]
#fn main() {
#[deprecated]
fn foo() {}

fn bar() {
    foo();
}
#}

This will produce:

warning: use of deprecated item 'foo'
 --> src/lib.rs:7:5
  |
7 |     foo();
  |     ^^^
  |

This lint detects floating-point literals used in patterns. Some example code that triggers this lint:

# #![allow(unused_variables)]
#fn main() {
let x = 42.0;

match x {
    5.0 => {},
    _ => {},
}
#}

This will produce:

warning: floating-point literals cannot be used in patterns
 --> src/main.rs:4:9
  |
4 |         5.0 => {},
  |         ^^^
  |
  = note: #[warn(illegal_floating_point_literal_pattern)] on by default
  = warning: this was previously accepted by the compiler but is being phased out; it will become a hard error in a future release!
  = note: for more information, see issue #41620 <https://github.com/rust-lang/rust/issues/41620>

This lint detects proper use of libc types in foreign modules. Some example code that triggers this lint:

# #![allow(unused_variables)]
#fn main() {
extern "C" {
    static STATIC: String;
}
#}

This will produce:

warning: found struct without foreign-function-safe representation annotation in foreign module, consider adding a #[repr(C)] attribute to the type
 --> src/main.rs:2:20
  |
2 |     static STATIC: String;
  |                    ^^^^^^
  |

This lint detects generic lifetime arguments in path segments with late bound lifetime parameters. Some example code that triggers this lint:

struct S;

impl S {
    fn late<'a, 'b>(self, _: &'a u8, _: &'b u8) {}
}

fn main() {
    S.late::<'static>(&0, &0);
}

This will produce:

warning: cannot specify lifetime arguments explicitly if late bound lifetime parameters are present
 --> src/main.rs:8:14
  |
4 |     fn late<'a, 'b>(self, _: &'a u8, _: &'b u8) {}
  |             -- the late bound lifetime parameter is introduced here
...
8 |     S.late::<'static>(&0, &0);
  |              ^^^^^^^
  |
  = note: #[warn(late_bound_lifetime_arguments)] on by default
  = warning: this was previously accepted by the compiler but is being phased out; it will become a hard error in a future release!
  = note: for more information, see issue #42868 <https://github.com/rust-lang/rust/issues/42868>

This lint detects types, variants, traits and type parameters that don't have camel case names. Some example code that triggers this lint:

# #![allow(unused_variables)]
#fn main() {
struct s;
#}

This will produce:

warning: type `s` should have a camel case name such as `S`
 --> src/main.rs:1:1
  |
1 | struct s;
  | ^^^^^^^^^
  |

This lint detects using Struct { x: x } instead of Struct { x } in a pattern. Some example code that triggers this lint:

struct Point {
    x: i32,
    y: i32,
}


fn main() {
    let p = Point {
        x: 5,
        y: 5,
    };

    match p {
        Point { x: x, y: y } => (),
    }
}

This will produce:

warning: the `x:` in this pattern is redundant
  --> src/main.rs:14:17
   |
14 |         Point { x: x, y: y } => (),
   |                 --^^
   |                 |
   |                 help: remove this
   |

warning: the `y:` in this pattern is redundant
  --> src/main.rs:14:23
   |
14 |         Point { x: x, y: y } => (),
   |                       --^^
   |                       |
   |                       help: remove this

This lint detects variables, methods, functions, lifetime parameters and modules that don't have snake case names. Some example code that triggers this lint:

# #![allow(unused_variables)]
#fn main() {
let X = 5;
#}

This will produce:

warning: variable `X` should have a snake case name such as `x`
 --> src/main.rs:2:9
  |
2 |     let X = 5;
  |         ^
  |

This lint detects static constants that don't have uppercase identifiers. Some example code that triggers this lint:

# #![allow(unused_variables)]
#fn main() {
static x: i32 = 5;
#}

This will produce:

warning: static variable `x` should have an upper case name such as `X`
 --> src/main.rs:1:1
  |
1 | static x: i32 = 5;
  | ^^^^^^^^^^^^^^^^^^
  |

This lint detects generic items must be mangled. Some example code that triggers this lint:

# #![allow(unused_variables)]
#fn main() {
#[no_mangle]
fn foo<T>(t: T) {

}
#}

This will produce:

warning: functions generic over types must be mangled
 --> src/main.rs:2:1
  |
1 |   #[no_mangle]
  |   ------------ help: remove this attribute
2 | / fn foo<T>(t: T) {
3 | |
4 | | }
  | |_^
  |

This lint detects path statements with no effect. Some example code that triggers this lint:

# #![allow(unused_variables)]
#fn main() {
let x = 42;

x;
#}

This will produce:

warning: path statement with no effect
 --> src/main.rs:3:5
  |
3 |     x;
  |     ^^
  |

This lint detects patterns in functions without body were that were previously erroneously allowed. Some example code that triggers this lint:

# #![allow(unused_variables)]
#fn main() {
trait Trait {
    fn foo(mut arg: u8);
}
#}

This will produce:

warning: patterns aren't allowed in methods without bodies
 --> src/main.rs:2:12
  |
2 |     fn foo(mut arg: u8);
  |            ^^^^^^^
  |
  = note: #[warn(patterns_in_fns_without_body)] on by default
  = warning: this was previously accepted by the compiler but is being phased out; it will become a hard error in a future release!
  = note: for more information, see issue #35203 <https://github.com/rust-lang/rust/issues/35203>

To fix this, remove the pattern; it can be used in the implementation without being used in the definition. That is:

# #![allow(unused_variables)]
#fn main() {
trait Trait {
    fn foo(arg: u8);
}

impl Trait for i32 {
    fn foo(mut arg: u8) {

    }
}
#}

This lint detects when compiler plugins are used as ordinary library in non-plugin crate. Some example code that triggers this lint:

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

extern crate macro_crate_test;

This lint detects private items in public interfaces not caught by the old implementation. Some example code that triggers this lint:

pub trait Trait {
    type A;
}

pub struct S;

mod foo {
    struct Z;

    impl ::Trait for ::S {
        type A = Z;
    }
}
# fn main() {}

This will produce:

error[E0446]: private type `foo::Z` in public interface
  --> src/main.rs:11:9
   |
11 |         type A = Z;
   |         ^^^^^^^^^^^ can't leak private type

This lint detects functions marked #[no_mangle] that are also private. Given that private functions aren't exposed publicly, and #[no_mangle] controls the public symbol, this combination is erroneous. Some example code that triggers this lint:

# #![allow(unused_variables)]
#fn main() {
#[no_mangle]
fn foo() {}
#}

This will produce:

warning: function is marked #[no_mangle], but not exported
 --> src/main.rs:2:1
  |
2 | fn foo() {}
  | -^^^^^^^^^^
  | |
  | help: try making it public: `pub`
  |

To fix this, either make it public or remove the #[no_mangle].

This lint detects any statics marked #[no_mangle] that are private. Given that private statics aren't exposed publicly, and #[no_mangle] controls the public symbol, this combination is erroneous. Some example code that triggers this lint:

# #![allow(unused_variables)]
#fn main() {
#[no_mangle]
static X: i32 = 4;
#}

This will produce:

warning: static is marked #[no_mangle], but not exported
 --> src/main.rs:2:1
  |
2 | static X: i32 = 4;
  | -^^^^^^^^^^^^^^^^^
  | |
  | help: try making it public: `pub`
  |

To fix this, either make it public or remove the #[no_mangle].

This lint detects lints that have been renamed or removed. Some example code that triggers this lint:

# #![allow(unused_variables)]
#![deny(raw_pointer_derive)]
#fn main() {
#}

This will produce:

warning: lint raw_pointer_derive has been removed: using derive with raw pointers is ok
 --> src/main.rs:1:9
  |
1 | #![deny(raw_pointer_derive)]
  |         ^^^^^^^^^^^^^^^^^^
  |

To fix this, either remove the lint or use the new name.

This lint detects borrowing a field in the interior of a packed structure with alignment other than 1. Some example code that triggers this lint:

#[repr(packed)]
pub struct Unaligned<T>(pub T);

pub struct Foo {
    start: u8,
    data: Unaligned<u32>,
}

fn main() {
    let x = Foo { start: 0, data: Unaligned(1) };
    let y = &x.data.0;
}

This will produce:

warning: borrow of packed field requires unsafe function or block (error E0133)
  --> src/main.rs:11:13
   |
11 |     let y = &x.data.0;
   |             ^^^^^^^^^
   |
   = note: #[warn(safe_packed_borrows)] on by default
   = warning: this was previously accepted by the compiler but is being phased out; it will become a hard error in a future release!
   = note: for more information, see issue #46043 <https://github.com/rust-lang/rust/issues/46043>

This lint detects a #[feature] attribute that's since been made stable. Some example code that triggers this lint:

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

This will produce:

warning: this feature has been stable since 1.0.0. Attribute no longer needed
 --> src/main.rs:1:12
  |
1 | #![feature(test_accepted_feature)]
  |            ^^^^^^^^^^^^^^^^^^^^^
  |

To fix, simply remove the #![feature] attribute, as it's no longer needed.

This lint detects bounds in type aliases. These are not currently enforced. Some example code that triggers this lint:

# #![allow(unused_variables)]
#fn main() {
type SendVec<T: Send> = Vec<T>;
#}

This will produce:

warning: type alias is never used: `SendVec`
 --> src/main.rs:1:1
  |
1 | type SendVec<T: Send> = Vec<T>;
  | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  |

This lint detects raw pointer to an inference variable. Some example code that triggers this lint:

# #![allow(unused_variables)]
#fn main() {
let data = std::ptr::null();
let _ = &data as *const *const ();

if data.is_null() {}
#}

This will produce:

warning: type annotations needed
 --> src/main.rs:4:13
  |
4 |     if data.is_null() {}
  |             ^^^^^^^
  |
  = note: #[warn(tyvar_behind_raw_pointer)] on by default
  = warning: this was previously accepted by the compiler but is being phased out; it will become a hard error in the 2018 edition!
  = note: for more information, see issue #46906 <https://github.com/rust-lang/rust/issues/46906>

This lint detects functions that cannot return without calling themselves. Some example code that triggers this lint:

# #![allow(unused_variables)]
#fn main() {
fn foo() {
    foo();
}
#}

This will produce:

warning: function cannot return without recursing
 --> src/main.rs:1:1
  |
1 | fn foo() {
  | ^^^^^^^^ cannot return without recursing
2 |     foo();
  |     ----- recursive call site
  |

This lint detects use of unions that contain fields with possibly non-trivial drop code. Some example code that triggers this lint:

# #![allow(unused_variables)]
#![feature(untagged_unions)]

#fn main() {
union U {
    s: String,
}
#}

This will produce:

warning: union contains a field with possibly non-trivial drop code, drop code of union fields is ignored when dropping the union
 --> src/main.rs:4:5
  |
4 |     s: String,
  |     ^^^^^^^^^
  |

This lint detects unrecognized lint attribute. Some example code that triggers this lint:

#[allow(not_a_real_lint)]

This will produce:

warning: unknown lint: `not_a_real_lint`
 --> src/main.rs:1:10
  |
1 | #![allow(not_a_real_lint)]
  |          ^^^^^^^^^^^^^^^
  |

This lint detects unreachable code paths. Some example code that triggers this lint:

# #![allow(unused_variables)]
#fn main() {
panic!("we never go past here!");

let x = 5;
#}

This will produce:

warning: unreachable statement
 --> src/main.rs:4:5
  |
4 |     let x = 5;
  |     ^^^^^^^^^^
  |

This lint detects unreachable patterns. Some example code that triggers this lint:

# #![allow(unused_variables)]
#fn main() {
let x = 5;
match x {
    y => (),
    5 => (),
}
#}

This will produce:

warning: unreachable pattern
 --> src/main.rs:5:5
  |
5 |     5 => (),
  |     ^
  |

The y pattern will always match, so the five is impossible to reach. Remember, match arms match in order, you probably wanted to put the 5 case above the y case.

This lint detects that you've used a name that the standard library plans to add in the future, which means that your code may fail to compile without additional type annotations in the future. Either rename, or add those annotations now.

This lint detects unnecessary allocations that can be eliminated.

This lint detects assignments that will never be read. Some example code that triggers this lint:

# #![allow(unused_variables)]
#fn main() {
let mut x = 5;
x = 6;
#}

This will produce:

warning: value assigned to `x` is never read
 --> src/main.rs:4:5
  |
4 |     x = 6;
  |     ^
  |

This lint detects attributes that were not used by the compiler. Some example code that triggers this lint:

# #![allow(unused_variables)]
#![feature(custom_attribute)]

#![mutable_doc]
#fn main() {
#}

This will produce:

warning: unused attribute
 --> src/main.rs:4:1
  |
4 | #![mutable_doc]
  | ^^^^^^^^^^^^^^^
  |

This lint detects comparisons made useless by limits of the types involved. Some example code that triggers this lint:

# #![allow(unused_variables)]
#fn main() {
fn foo(x: u8) {
    x >= 0;
}
#}

This will produce:

warning: comparison is useless due to type limits
 --> src/main.rs:6:5
  |
6 |     x >= 0;
  |     ^^^^^^
  |

This lint detects doc comments that aren't used by rustdoc. Some example code that triggers this lint:

# #![allow(unused_variables)]
#fn main() {
/// docs for x
let x = 12;
#}

This will produce:

warning: doc comment not used by rustdoc
 --> src/main.rs:2:5
  |
2 |     /// docs for x
  |     ^^^^^^^^^^^^^^
  |

This lint detects unused or unknown features found in crate-level #[feature] directives. To fix this, simply remove the feature flag.

This lint detects imports that are never used. Some example code that triggers this lint:

# #![allow(unused_variables)]
#fn main() {
use std::collections::HashMap;
#}

This will produce:

warning: unused import: `std::collections::HashMap`
 --> src/main.rs:1:5
  |
1 | use std::collections::HashMap;
  |     ^^^^^^^^^^^^^^^^^^^^^^^^^
  |

This lint detects macros that were not used. Some example code that triggers this lint:

macro_rules! unused {
    () => {};
}

fn main() {
}

This will produce:

warning: unused macro definition
 --> src/main.rs:1:1
  |
1 | / macro_rules! unused {
2 | |     () => {};
3 | | }
  | |_^
  |

This lint detects unused result of a type flagged as #[must_use]. Some example code that triggers this lint:

fn returns_result() -> Result<(), ()> {
    Ok(())
}

fn main() {
    returns_result();
}

This will produce:

warning: unused `std::result::Result` that must be used
 --> src/main.rs:6:5
  |
6 |     returns_result();
  |     ^^^^^^^^^^^^^^^^^
  |

This lint detects mut variables which don't need to be mutable. Some example code that triggers this lint:

# #![allow(unused_variables)]
#fn main() {
let mut x = 5;
#}

This will produce:

warning: variable does not need to be mutable
 --> src/main.rs:2:9
  |
2 |     let mut x = 5;
  |         ----^
  |         |
  |         help: remove this `mut`
  |

This lint detects if, match, while and return with parentheses; they do not need them. Some example code that triggers this lint:

# #![allow(unused_variables)]
#fn main() {
if(true) {}
#}

This will produce:

warning: unnecessary parentheses around `if` condition
 --> src/main.rs:2:7
  |
2 |     if(true) {}
  |       ^^^^^^ help: remove these parentheses
  |

This lint detects unnecessary use of an unsafe block. Some example code that triggers this lint:

# #![allow(unused_variables)]
#fn main() {
unsafe {}
#}

This will produce:

warning: unnecessary `unsafe` block
 --> src/main.rs:2:5
  |
2 |     unsafe {}
  |     ^^^^^^ unnecessary `unsafe` block
  |

This lint detects variables which are not used in any way. Some example code that triggers this lint:

# #![allow(unused_variables)]
#fn main() {
let x = 5;
#}

This will produce:

warning: unused variable: `x`
 --> src/main.rs:2:9
  |
2 |     let x = 5;
  |         ^ help: consider using `_x` instead
  |

This lint is a bit special; by changing its level, you change every other warning that would produce a warning to whatever value you'd like:

# #![allow(unused_variables)]
#![deny(warnings)]
#fn main() {
#}

As such, you won't ever trigger this lint in your code directly.

This lint detects while true { }. Some example code that triggers this lint:

# #![allow(unused_variables)]
#fn main() {
while true {

}
#}

This will produce:

warning: denote infinite loops with `loop { ... }`
 --> src/main.rs:2:5
  |
2 |     while true {
  |     ^^^^^^^^^^ help: use `loop`
  |

These lints are all set to the 'deny' level by default.

This lint detects that a shift exceeds the type's number of bits. Some example code that triggers this lint:

1_i32 << 32;

This will produce:

error: bitshift exceeds the type's number of bits
 --> src/main.rs:2:5
  |
2 |     1_i32 << 32;
  |     ^^^^^^^^^^^
  |

This lint detects type parameter default erroneously allowed in invalid location. Some example code that triggers this lint:

fn foo<T=i32>(t: T) {}

This will produce:

error: defaults for type parameters are only allowed in `struct`, `enum`, `type`, or `trait` definitions.
 --> src/main.rs:4:8
  |
4 | fn foo<T=i32>(t: T) {}
  |        ^
  |
  = note: #[deny(invalid_type_param_default)] on by default
  = warning: this was previously accepted by the compiler but is being phased out; it will become a hard error in a future release!
  = note: for more information, see issue #36887 <https://github.com/rust-lang/rust/issues/36887>

RFC 1506 modified some visibility rules, and changed the visibility of struct constructors. Some example code that triggers this lint:

mod m {
    pub struct S(u8);
    
    fn f() {
        // this is trying to use S from the 'use' line, but because the `u8` is
        // not pub, it is private
        ::S;
    }
}

use m::S;

This will produce:

error: private struct constructors are not usable through re-exports in outer modules
 --> src/main.rs:5:9
  |
5 |         ::S;
  |         ^^^
  |
  = note: #[deny(legacy_constructor_visibility)] on by default
  = warning: this was previously accepted by the compiler but is being phased out; it will become a hard error in a future release!
  = note: for more information, see issue #39207 <https://github.com/rust-lang/rust/issues/39207>

The legacy_directory_ownership warning is issued when

• There is a non-inline module with a #[path] attribute (e.g. #[path = "foo.rs"] mod bar;),
• The module's file ("foo.rs" in the above example) is not named "mod.rs", and
• The module's file contains a non-inline child module without a #[path] attribute.

The warning can be fixed by renaming the parent module to "mod.rs" and moving it into its own directory if appropriate.

The missing_fragment_specifier warning is issued when an unused pattern in a macro_rules! macro definition has a meta-variable (e.g. $e) that is not followed by a fragment specifier (e.g. :expr).

This warning can always be fixed by removing the unused pattern in the macro_rules! macro definition.

This lint catches transmuting from &T to &mut T because it is undefined behavior. Some example code that triggers this lint:

unsafe {
    let y = std::mem::transmute::<&i32, &mut i32>(&5);
}

This will produce:

error: mutating transmuted &mut T from &T may cause undefined behavior, consider instead using an UnsafeCell
 --> src/main.rs:3:17
  |
3 |         let y = std::mem::transmute::<&i32, &mut i32>(&5);
  |                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  |

This lint detects any const items with the #[no_mangle] attribute. Constants do not have their symbols exported, and therefore, this probably means you meant to use a static, not a const. Some example code that triggers this lint:

#[no_mangle]
const FOO: i32 = 5;

This will produce:

error: const items should never be #[no_mangle]
 --> src/main.rs:3:1
  |
3 | const FOO: i32 = 5;
  | -----^^^^^^^^^^^^^^
  | |
  | help: try a static value: `pub static`
  |

This lint detects literal out of range for its type. Some example code that triggers this lint:

# #![allow(unused_variables)]
#fn main() {
let x: u8 = 1000;
#}

This will produce:

error: literal out of range for u8
 --> src/main.rs:2:17
  |
2 |     let x: u8 = 1000;
  |                 ^^^^
  |

This lint detects incorrect parentheses. Some example code that triggers this lint:

let x = 5 as usize();

This will produce:

error: parenthesized parameters may only be used with a trait
 --> src/main.rs:2:21
  |
2 |   let x = 5 as usize();
  |                     ^^
  |
  = note: #[deny(parenthesized_params_in_types_and_modules)] on by default
  = warning: this was previously accepted by the compiler but is being phased out; it will become a hard error in a future release!
  = note: for more information, see issue #42238 <https://github.com/rust-lang/rust/issues/42238>

To fix it, remove the ()s.

This lint detects a specific situation of re-exporting a private extern crate;

In older versions of Rust, there was a soundness issue where extern statics were allowed to be accessed in safe code. This lint now catches and denies this kind of code.

This lint detects an unknown crate type found in a #[crate_type] directive. Some example code that triggers this lint:

#![crate_type="lol"]

This will produce:

error: invalid `crate_type` value
 --> src/lib.rs:1:1
  |
1 | #![crate_type="lol"]
  | ^^^^^^^^^^^^^^^^^^^^
  |

All of these options are passed to rustc via the -C flag, short for "codegen." You can see a version of this list for your exact compiler by running rustc -C help.

This option is deprecated and does nothing.

This flag lets you control which linker rustc invokes to link your code.

This flag lets you append a single extra argument to the linker invocation.

"Append" is significant; you can pass this flag multiple times to add multiple arguments.

This flag lets you append multiple extra arguments to the linker invocation. The options should be separated by spaces.

This flag lets you control the linker flavor used by rustc. If a linker is given with the -C linker flag described above then the linker flavor is inferred from the value provided. If no linker is given then the linker flavor is used to determine the linker to use. Every rustc target defaults to some linker flavor.

Normally, the linker will remove dead code. This flag disables this behavior.

An example of when this flag might be useful is when trying to construct code coverage metrics.

This flag instructs LLVM to use link time optimizations.

It takes one of two values, thin and fat. 'thin' LTO is a new feature of LLVM, 'fat' referring to the classic version of LTO.

This instructs rustc to generate code specifically for a particular processor.

You can run rustc --print target-cpus to see the valid options to pass here. Additionally, native can be passed to use the processor of the host machine.

Individual targets will support different features; this flag lets you control enabling or disabling a feature.

To see the valid options and an example of use, run rustc --print target-features.

This flag can be used to add extra LLVM passes to the compilation.

The list must be separated by spaces.

This flag can be used to pass a list of arguments directly to LLVM.

The list must be separated by spaces.

rustc will generate temporary files during compilation; normally it will delete them after it's done with its work. This option will cause them to be preserved instead of removed.

This option allows you to set the value of rpath.

This flag allows you to control the behavior of integer overflow. This flag can be passed many options:

• To turn overflow checks on: y, yes, or on.
• To turn overflow checks off: n, no, or off.

The pass manager comes pre-populated with a list of passes; this flag ensures that list is empty.

By default, rustc will attempt to vectorize loops. This flag will turn that behavior off.

By default, rustc will attempt to vectorize loops using superword-level parallelism. This flag will turn that behavior off.

This option will make rustc generate code using "soft floats." By default, a lot of hardware supports floating point instructions, and so the code generated will take advantage of this. "soft floats" emulate floating point instructions in software.

By default, rustc prefers to statically link dependencies. This option will make it use dynamic linking instead.

LLVM comes with an internal assembler; this option will let you use an external assembler instead.

This flag allows you to disable the red zone. This flag can be passed many options:

• To enable the red zone: y, yes, or on.
• To disable it: n, no, or off.

This option lets you choose which relocation model to use.

To find the valid options for this flag, run rustc --print relocation-models.

This option lets you choose which code model to use.

To find the valid options for this flag, run rustc --print code-models.

This option allows you to control the metadata used for symbol mangling.

This option allows you to put extra data in each output filename.

This flag lets you control how many threads are used when doing code generation.

Increasing parallelism may speed up compile times, but may also produce slower code.

This flag lets you print remarks for these optimization passes.

The list of passes should be separated by spaces.

all will remark on every pass.

This option is deprecated and does nothing.

This flag lets you control debug information:

• 0: no debug info at all
• 1: line tables only
• 2: full debug info

This flag lets you control the optimization level.

• 0: no optimizations, also turn on cfg(debug_assertions).
• 1: basic optimizations
• 2: some optimizations
• 3: all optimizations
• s: optimize for binary size
• z: optimize for binary size, but also turn off loop vectorization.

This flag lets you turn cfg(debug_assertions) on or off.

This option lets you set the threshold for inlining a function.

The default is 225.

This option lets you control what happens when the code panics.

• abort: terminate the process upon panic
• unwind: unwind the stack upon panic

This flag allows you to enable incremental compilation.

rustc is a cross-compiler by default. This means that you can use any compiler to build for any architecture. The list of targets are the possible architectures that you can build for.

To see all the options that you can set with a target, see the docs here.

To compile to a particular target, use the --target flag:

$ rustc src/main.rs --target=wasm32-unknown-unknown

rustc ships with the ability to compile to many targets automatically, we call these "built-in" targets, and they generally correspond to targets that the team is supporting directly.

To see the list of built-in targets, you can run rustc --print target-list, or look at the API docs. Each module there defines a builder for a particular target.

If you'd like to build for a target that is not yet supported by rustc, you can use a "custom target specification" to define a target. These target specification files are JSON. To see the JSON for the host target, you can run:

$ rustc +nightly -Z unstable-options --print target-spec-json

To see it for a different target, add the --target flag:

$ rustc +nightly -Z unstable-options --target=wasm32-unknown-unknown --print target-spec-json

To use a custom target, see xargo.

The -C linker-plugin-lto flag allows for deferring the LTO optimization to the actual linking step, which in turn allows for performing interprocedural optimizations across programming language boundaries if all the object files being linked were created by LLVM based toolchains. The prime example here would be linking Rust code together with Clang-compiled C/C++ code.

There are two main cases how linker plugin based LTO can be used:

• compiling a Rust staticlib that is used as a C ABI dependency
• compiling a Rust binary where rustc invokes the linker

In both cases the Rust code has to be compiled with -C linker-plugin-lto and the C/C++ code with -flto or -flto=thin so that object files are emitted as LLVM bitcode.

In this case the Rust compiler just has to make sure that the object files in the staticlib are in the right format. For linking, a linker with the LLVM plugin must be used (e.g. LLD).

Using rustc directly:

# Compile the Rust staticlib
rustc --crate-type=staticlib -Clinker-plugin-lto -Copt-level=2 ./lib.rs
# Compile the C code with `-flto=thin`
clang -c -O2 -flto=thin -o main.o ./main.c
# Link everything, making sure that we use an appropriate linker
clang -flto=thin -fuse-ld=lld -L . -l"name-of-your-rust-lib" -o main -O2 ./cmain.o

Using cargo:

# Compile the Rust staticlib
RUSTFLAGS="-Clinker-plugin-lto" cargo build --release
# Compile the C code with `-flto=thin`
clang -c -O2 -flto=thin -o main.o ./main.c
# Link everything, making sure that we use an appropriate linker
clang -flto=thin -fuse-ld=lld -L . -l"name-of-your-rust-lib" -o main -O2 ./cmain.o

In this case the linker will be invoked by rustc. We again have to make sure that an appropriate linker is used.

Using rustc directly:

# Compile C code with `-flto`
clang ./clib.c -flto=thin -c -o ./clib.o -O2
# Create a static library from the C code
ar crus ./libxyz.a ./clib.o

# Invoke `rustc` with the additional arguments
rustc -Clinker-plugin-lto -L. -Copt-level=2 -Clinker=clang -Clink-arg=-fuse-ld=lld ./main.rs

Using cargo directly:

# Compile C code with `-flto`
clang ./clib.c -flto=thin -c -o ./clib.o -O2
# Create a static library from the C code
ar crus ./libxyz.a ./clib.o

# Set the linking arguments via RUSTFLAGS
RUSTFLAGS="-Clinker-plugin-lto -Clinker=clang -Clink-arg=-fuse-ld=lld" cargo build --release

If one wants to use a linker other than LLD, the LLVM linker plugin has to be specified explicitly. Otherwise the linker cannot read the object files. The path to the plugin is passed as an argument to the -Clinker-plugin-lto option:

rustc -Clinker-plugin-lto="/path/to/LLVMgold.so" -L. -Copt-level=2 ./main.rs

In order for this kind of LTO to work, the LLVM linker plugin must be able to handle the LLVM bitcode produced by both rustc and clang.

Best results are achieved by using a rustc and clang that are based on the exact same version of LLVM. One can use rustc -vV in order to view the LLVM used by a given rustc version. Note that the version number given here is only an approximation as Rust sometimes uses unstable revisions of LLVM. However, the approximation is usually reliable.

The following table shows known good combinations of toolchain versions.

Note that the compatibility policy for this feature might change in the future.

We'd love to have your help improving rustc! To that end, we've written a whole book on its internals, how it works, and how to get started working on it. To learn more, you'll want to check that out.

If you would like to contribute to this book, you can find its source in the rustc source at src/doc/rustc.