What is rustc?

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.

Basic usage

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.

Command-line Arguments

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

-h/--help: get help

This flag will print out help information for rustc.

--cfg: configure the compilation environment

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

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.

--check-cfg: configure compile-time checking of conditional compilation

This flag enables checking conditional configurations of the crate at compile-time, specifically it helps configure the set of expected cfg names and values, in order to check that every reachable #[cfg] matches the expected config names and values.

This is different from the --cfg flag above which activates some config but do not expect them. This is useful to prevent stalled conditions, typos, ...

Refer to the Checking conditional configurations of this book for further details and explanation.

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

-L: add a directory to the library search path

The -L flag adds a path to search for external crates and libraries.

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, except frameworks. This is the default if KIND is not specified.

-l: link the generated crate to a native library

Syntax: -l [KIND[:MODIFIERS]=]NAME[:RENAME].

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.

If the kind is specified, then linking modifiers can be attached to it. Modifiers are specified as a comma-delimited string with each modifier prefixed with either a + or - to indicate that the modifier is enabled or disabled, respectively. Specifying multiple modifiers arguments in a single link attribute, or multiple identical modifiers in the same modifiers argument is not currently supported.
Example: -l static:+whole-archive=mylib.

The kind of library and the modifiers can also 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 by default, except when building a static executable. 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.

Linking modifiers: whole-archive

This modifier is only compatible with the static linking kind. Using any other kind will result in a compiler error.

+whole-archive means that the static library is linked as a whole archive without throwing any object files away.

This modifier translates to --whole-archive for ld-like linkers, to /WHOLEARCHIVE for link.exe, and to -force_load for ld64. The modifier does nothing for linkers that don't support it.

The default for this modifier is -whole-archive.

Linking modifiers: bundle

This modifier is only compatible with the static linking kind. Using any other kind will result in a compiler error.

When building a rlib or staticlib +bundle means that the native static library will be packed into the rlib or staticlib archive, and then retrieved from there during linking of the final binary.

When building a rlib -bundle means that the native static library is registered as a dependency of that rlib "by name", and object files from it are included only during linking of the final binary, the file search by that name is also performed during final linking.
When building a staticlib -bundle means that the native static library is simply not included into the archive and some higher level build system will need to add it later during linking of the final binary.

This modifier has no effect when building other targets like executables or dynamic libraries.

The default for this modifier is +bundle.

Linking modifiers: verbatim

This modifier is compatible with all linking kinds.

+verbatim means that rustc itself won't add any target-specified library prefixes or suffixes (like lib or .a) to the library name, and will try its best to ask for the same thing from the linker.

For ld-like linkers supporting GNU extensions rustc will use the -l:filename syntax (note the colon) when passing the library, so the linker won't add any prefixes or suffixes to it. See -l namespec in ld documentation for more details.
For linkers not supporting any verbatim modifiers (e.g. link.exe or ld64) the library name will be passed as is. So the most reliable cross-platform use scenarios for this option are when no linker is involved, for example bundling native libraries into rlibs.

-verbatim means that rustc will either add a target-specific prefix and suffix to the library name before passing it to linker, or won't prevent linker from implicitly adding it.
In case of raw-dylib kind in particular .dll will be added to the library name on Windows.

The default for this modifier is -verbatim.

NOTE: Even with +verbatim and -l:filename syntax ld-like linkers do not typically support passing absolute paths to libraries. Usually such paths need to be passed as input files without using any options like -l, e.g. ld /my/absolute/path.
-Clink-arg=/my/absolute/path can be used for doing this from stable rustc.

--crate-type: a list of types of crates for the compiler to emit

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.

--crate-name: specify the name of the crate being built

This informs rustc of the name of your crate.

--edition: specify the edition to use

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

--emit: specifies the types of output files to generate

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 libCRATE_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.

Output files are written to the current directory unless the --out-dir flag is used.

Custom paths for individual emit kinds

Each emit type can optionally be followed by = to specify an explicit output path that only applies to the output of that type. For example:

• --emit=link,dep-info=/path/to/dep-info.d
  • Emit the crate itself as normal, and also emit dependency info to the specified path.
• --emit=llvm-ir=-,mir
  • Emit MIR to the default filename (based on crate name), and emit LLVM IR to stdout.

Emitting to stdout

When using --emit or -o, output can be sent to stdout by specifying - as the path (e.g. -o -).

Binary output types can only be written to stdout if it is not a tty. Text output types (asm, dep-info, llvm-ir and mir) can be written to stdout regardless of whether it is a tty or not.

Only one type of output can be written to stdout. Attempting to write multiple types to stdout at the same time will result in an error.

--print: print compiler information

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.
• target-libdir — Path to the target libdir.
• host-tuple — The target-tuple string of the host compiler (e.g. x86_64-unknown-linux-gnu)
• 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. This flag is unsafe. See known issues for more details.
• 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.
• link-args — This flag does not disable the --emit step. When linking, this flag causes rustc to print the full linker invocation in a human-readable form. This can be useful when debugging linker options. The exact format of this debugging output is not a stable guarantee, other than that it will include the linker executable and the text of each command-line argument passed to the linker.
• deployment-target — The currently selected deployment target (or minimum OS version) for the selected Apple platform target. This value can be used or passed along to other components alongside a Rust build that need this information, such as C compilers. This returns rustc's minimum supported deployment target if no *_DEPLOYMENT_TARGET variable is present in the environment, or otherwise returns the variable's parsed value.

A filepath may optionally be specified for each requested information kind, in the format --print KIND=PATH, just like for --emit. When a path is specified, information will be written there instead of to stdout.

-g: include debug information

A synonym for -C debuginfo=2.

-O: optimize your code

A synonym for -C opt-level=3.

-o: filename of the output

This flag controls the output filename.

--out-dir: directory to write the output in

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

--explain: provide a detailed explanation of an error message

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

--test: build a test harness

When compiling this crate, rustc will ignore your main function and instead produce a test harness. See the Tests chapter for more information about tests.

--target: select a target triple to build

This controls which target to produce.

-W: set lint warnings

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

Note: The order of these lint level arguments is taken into account, see lint level via compiler flag for more information.

--force-warn: force a lint to warn

This flag sets the given lint to the forced warn level and the level cannot be overridden, even ignoring the lint caps.

-A: set lint allowed

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

Note: The order of these lint level arguments is taken into account, see lint level via compiler flag for more information.

-D: set lint denied

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

Note: The order of these lint level arguments is taken into account, see lint level via compiler flag for more information.

-F: set lint forbidden

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

Note: The order of these lint level arguments is taken into account, see lint level via compiler flag for more information.

-Z: set unstable options

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-internals -Z time-passes. Specifying options with -Z is only available on nightly. To view all available options run: rustc -Z help, or see The Unstable Book.

--cap-lints: set the most restrictive lint level

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

-C/--codegen: code generation options

This flag will allow you to set codegen options.

-V/--version: print a version

This flag will print out rustc's version.

-v/--verbose: use verbose output

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

--extern: specify where an external library is located

This flag allows you to pass the name and location for an external crate of a direct dependency. Indirect dependencies (dependencies of dependencies) are located using the -L flag. The given crate name is added to the extern prelude, similar to specifying extern crate within the root module. The given crate name does not need to match the name the library was built with.

Specifying --extern has one behavior difference from extern crate: --extern merely makes the crate a candidate for being linked; it does not actually link it unless it's actively used. In rare occasions you may wish to ensure a crate is linked even if you don't actively use it from your code: for example, if it changes the global allocator or if it contains #[no_mangle] symbols for use by other programming languages. In such cases you'll need to use extern crate.

This flag may be specified multiple times. This flag takes an argument with either of the following formats:

• CRATENAME=PATH — Indicates the given crate is found at the given path.
• CRATENAME — Indicates the given crate may be found in the search path, such as within the sysroot or via the -L flag.

The same crate name may be specified multiple times for different crate types. If both an rlib and dylib are found, an internal algorithm is used to decide which to use for linking. The -C prefer-dynamic flag may be used to influence which is used.

If the same crate name is specified with and without a path, the one with the path is used and the pathless flag has no effect.

--sysroot: Override the system root

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

--error-format: control how errors are produced

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. See the JSON chapter for more detail.
• short — Short, one-line messages.

--color: configure coloring of output

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.

--diagnostic-width: specify the terminal width for diagnostics

This flag takes a number that specifies the width of the terminal in characters. Formatting of diagnostics will take the width into consideration to make them better fit on the screen.

--remap-path-prefix: remap source names in 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.

When multiple remappings are given and several of them match, the last matching one is applied.

--json: configure json messages printed by the compiler

When the --error-format=json option is passed to rustc then all of the compiler's diagnostic output will be emitted in the form of JSON blobs. The --json argument can be used in conjunction with --error-format=json to configure what the JSON blobs contain as well as which ones are emitted.

With --error-format=json the compiler will always emit any compiler errors as a JSON blob, but the following options are also available to the --json flag to customize the output:

• diagnostic-short - json blobs for diagnostic messages should use the "short" rendering instead of the normal "human" default. This means that the output of --error-format=short will be embedded into the JSON diagnostics instead of the default --error-format=human.

• diagnostic-rendered-ansi - by default JSON blobs in their rendered field will contain a plain text rendering of the diagnostic. This option instead indicates that the diagnostic should have embedded ANSI color codes intended to be used to colorize the message in the manner rustc typically already does for terminal outputs. Note that this is usefully combined with crates like fwdansi to translate these ANSI codes on Windows to console commands or strip-ansi-escapes if you'd like to optionally remove the ansi colors afterwards.

• artifacts - this instructs rustc to emit a JSON blob for each artifact that is emitted. An artifact corresponds to a request from the --emit CLI argument, and as soon as the artifact is available on the filesystem a notification will be emitted.

• future-incompat - includes a JSON message that contains a report if the crate contains any code that may fail to compile in the future.

Note that it is invalid to combine the --json argument with the --color argument, and it is required to combine --json with --error-format=json.

See the JSON chapter for more detail.

@path: load command-line flags from a path

If you specify @path on the command-line, then it will open path and read command line options from it. These options are one per line; a blank line indicates an empty option. The file can use Unix or Windows style line endings, and must be encoded as UTF-8.

Codegen Options

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.

ar

This option is deprecated and does nothing.

code-model

This option lets you choose which code model to use.
Code models put constraints on address ranges that the program and its symbols may use.
With smaller address ranges machine instructions may be able to use more compact addressing modes.

The specific ranges depend on target architectures and addressing modes available to them.
For x86 more detailed description of its code models can be found in System V Application Binary Interface specification.

Supported values for this option are:

• tiny - Tiny code model.
• small - Small code model. This is the default model for majority of supported targets.
• kernel - Kernel code model.
• medium - Medium code model.
• large - Large code model.

Supported values can also be discovered by running rustc --print code-models.

codegen-units

This flag controls the maximum number of code generation units the crate is split into. It takes an integer greater than 0.

When a crate is split into multiple codegen units, LLVM is able to process them in parallel. Increasing parallelism may speed up compile times, but may also produce slower code. Setting this to 1 may improve the performance of generated code, but may be slower to compile.

The default value, if not specified, is 16 for non-incremental builds. For incremental builds the default is 256 which allows caching to be more granular.

collapse-macro-debuginfo

This flag controls whether code locations from a macro definition are collapsed into a single location associated with that macro's call site, when generating debuginfo for this crate.

This option, if passed, overrides both default collapsing behavior and #[collapse_debuginfo] attributes in code.

• y, yes, on, true: collapse code locations in debuginfo.
• n, no, off or false: do not collapse code locations in debuginfo.
• external: collapse code locations in debuginfo only if the macro comes from a different crate.

control-flow-guard

This flag controls whether LLVM enables the Windows Control Flow Guard platform security feature. This flag is currently ignored for non-Windows targets. It takes one of the following values:

• y, yes, on, true, checks, or no value: enable Control Flow Guard.
• nochecks: emit Control Flow Guard metadata without runtime enforcement checks (this should only be used for testing purposes as it does not provide security enforcement).
• n, no, off, false: do not enable Control Flow Guard (the default).

debug-assertions

This flag lets you turn cfg(debug_assertions) conditional compilation on or off. It takes one of the following values:

• y, yes, on, true, or no value: enable debug-assertions.
• n, no, off or false: disable debug-assertions.

If not specified, debug assertions are automatically enabled only if the opt-level is 0.

debuginfo

This flag controls the generation of debug information. It takes one of the following values:

• 0 or none: no debug info at all (the default).
• line-directives-only: line info directives only. For the nvptx* targets this enables profiling. For other use cases, line-tables-only is the better, more compatible choice.
• line-tables-only: line tables only. Generates the minimal amount of debug info for backtraces with filename/line number info, but not anything else, i.e. no variable or function parameter info.
• 1 or limited: debug info without type or variable-level information.
• 2 or full: full debug info.

Note: The -g flag is an alias for -C debuginfo=2.

default-linker-libraries

This flag controls whether or not the linker includes its default libraries. It takes one of the following values:

• y, yes, on, true: include default libraries.
• n, no, off or false or no value: exclude default libraries (the default).

For example, for gcc flavor linkers, this issues the -nodefaultlibs flag to the linker.

dlltool

On windows-gnu targets, this flag controls which dlltool rustc invokes to generate import libraries when using the raw-dylib link kind. It takes a path to the dlltool executable. If this flag is not specified, a dlltool executable will be inferred based on the host environment and target.

embed-bitcode

This flag controls whether or not the compiler embeds LLVM bitcode into object files. It takes one of the following values:

• y, yes, on, true or no value: put bitcode in rlibs (the default).
• n, no, off or false: omit bitcode from rlibs.

LLVM bitcode is required when rustc is performing link-time optimization (LTO). Embedded bitcode will appear in rustc-generated object files inside of a section whose name is defined by the target platform. Most of the time this is .llvmbc.

The use of -C embed-bitcode=no can significantly improve compile times and reduce generated file sizes if your compilation does not actually need bitcode (e.g. if you're not performing LTO). For these reasons, Cargo uses -C embed-bitcode=no whenever possible. Likewise, if you are building directly with rustc we recommend using -C embed-bitcode=no whenever you are not using LTO.

If combined with -C lto, -C embed-bitcode=no will cause rustc to abort at start-up, because the combination is invalid.

Note: if you're building Rust code with LTO then you probably don't even need the embed-bitcode option turned on. You'll likely want to use -Clinker-plugin-lto instead which skips generating object files entirely and simply replaces object files with LLVM bitcode. The only purpose for -Cembed-bitcode is when you're generating an rlib that is both being used with and without LTO. For example Rust's standard library ships with embedded bitcode since users link to it both with and without LTO.

This also may make you wonder why the default is yes for this option. The reason for that is that it's how it was for rustc 1.44 and prior. In 1.45 this option was added to turn off what had always been the default.

extra-filename

This option allows you to put extra data in each output filename. It takes a string to add as a suffix to the filename. See the --emit flag for more information.

force-frame-pointers

This flag forces the use of frame pointers. It takes one of the following values:

• y, yes, on, true or no value: force-enable frame pointers.
• n, no, off or false: do not force-enable frame pointers. This does not necessarily mean frame pointers will be removed.

The default behaviour, if frame pointers are not force-enabled, depends on the target.

force-unwind-tables

This flag forces the generation of unwind tables. It takes one of the following values:

• y, yes, on, true or no value: Unwind tables are forced to be generated.
• n, no, off or false: Unwind tables are not forced to be generated. If unwind tables are required by the target an error will be emitted.

The default if not specified depends on the target.

incremental

This flag allows you to enable incremental compilation, which allows rustc to save information after compiling a crate to be reused when recompiling the crate, improving re-compile times. This takes a path to a directory where incremental files will be stored.

inline-threshold

This option is deprecated and does nothing.

Consider using -Cllvm-args=--inline-threshold=....

instrument-coverage

This option enables instrumentation-based code coverage support. See the chapter on instrumentation-based code coverage for more information.

Note that while the -C instrument-coverage option is stable, the profile data format produced by the resulting instrumentation may change, and may not work with coverage tools other than those built and shipped with the compiler.

link-arg

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.

link-args

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

link-dead-code

Tries to generate and link dead code that would otherwise not be generated or linked. It takes one of the following values:

• y, yes, on, true or no value: try to keep dead code.
• n, no, off or false: remove dead code (the default).

This flag was historically used to help improve some older forms of code coverage measurement. Its use is not recommended.

link-self-contained

On windows-gnu, linux-musl, and wasi targets, this flag controls whether the linker will use libraries and objects shipped with Rust instead of those in the system. It takes one of the following values:

• no value: rustc will use heuristic to disable self-contained mode if system has necessary tools.
• y, yes, on, true: use only libraries/objects shipped with Rust.
• n, no, off or false: rely on the user or the linker to provide non-Rust libraries/objects.

This allows overriding cases when detection fails or user wants to use shipped libraries.

linker

This flag controls which linker rustc invokes to link your code. It takes a path to the linker executable. If this flag is not specified, the linker will be inferred based on the target. See also the linker-flavor flag for another way to specify the linker.

linker-flavor

This flag controls the linker flavor used by rustc. If a linker is given with the -C linker flag, 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. Valid options are:

• em: use Emscripten emcc.
• gcc: use the cc executable, which is typically gcc or clang on many systems.
• ld: use the ld executable.
• msvc: use the link.exe executable from Microsoft Visual Studio MSVC.
• wasm-ld: use the wasm-ld executable, a port of LLVM lld for WebAssembly.
• ld64.lld: use the LLVM lld executable with the -flavor darwin flag for Apple's ld.
• ld.lld: use the LLVM lld executable with the -flavor gnu flag for GNU binutils' ld.
• lld-link: use the LLVM lld executable with the -flavor link flag for Microsoft's link.exe.

linker-plugin-lto

This flag defers LTO optimizations to the linker. See linker-plugin-LTO for more details. It takes one of the following values:

• y, yes, on, true or no value: enable linker plugin LTO.
• n, no, off or false: disable linker plugin LTO (the default).
• A path to the linker plugin.

More specifically this flag will cause the compiler to replace its typical object file output with LLVM bitcode files. For example an rlib produced with -Clinker-plugin-lto will still have *.o files in it, but they'll all be LLVM bitcode instead of actual machine code. It is expected that the native platform linker is capable of loading these LLVM bitcode files and generating code at link time (typically after performing optimizations).

Note that rustc can also read its own object files produced with -Clinker-plugin-lto. If an rlib is only ever going to get used later with a -Clto compilation then you can pass -Clinker-plugin-lto to speed up compilation and avoid generating object files that aren't used.

llvm-args

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

The list must be separated by spaces.

Pass --help to see a list of options.

lto

This flag controls whether LLVM uses link time optimizations to produce better optimized code, using whole-program analysis, at the cost of longer linking time. It takes one of the following values:

• y, yes, on, true, fat, or no value: perform "fat" LTO which attempts to perform optimizations across all crates within the dependency graph.
• n, no, off, false: disables LTO.
• thin: perform "thin" LTO. This is similar to "fat", but takes substantially less time to run while still achieving performance gains similar to "fat".

If -C lto is not specified, then the compiler will attempt to perform "thin local LTO" which performs "thin" LTO on the local crate only across its codegen units. When -C lto is not specified, LTO is disabled if codegen units is 1 or optimizations are disabled (-C opt-level=0). That is:

• When -C lto is not specified:
  • codegen-units=1: disable LTO.
  • opt-level=0: disable LTO.
• When -C lto is specified:
  • lto: 16 codegen units, perform fat LTO across crates.
  • codegen-units=1 + lto: 1 codegen unit, fat LTO across crates.

See also linker-plugin-lto for cross-language LTO.

metadata

This option allows you to control the metadata used for symbol mangling. This takes a space-separated list of strings. Mangled symbols will incorporate a hash of the metadata. This may be used, for example, to differentiate symbols between two different versions of the same crate being linked.

no-prepopulate-passes

This flag tells the pass manager to use an empty list of passes, instead of the usual pre-populated list of passes.

no-redzone

This flag allows you to disable the red zone. It takes one of the following values:

• y, yes, on, true or no value: disable the red zone.
• n, no, off or false: enable the red zone.

The default behaviour, if the flag is not specified, depends on the target.

no-stack-check

This option is deprecated and does nothing.

no-vectorize-loops

This flag disables loop vectorization.

no-vectorize-slp

This flag disables vectorization using superword-level parallelism.

opt-level

This flag controls the optimization level.

• 0: no optimizations, also turns on cfg(debug_assertions) (the default).
• 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.

Note: The -O flag is an alias for -C opt-level=3.

The default is 0.

overflow-checks

This flag allows you to control the behavior of runtime integer overflow. When overflow-checks are enabled, a panic will occur on overflow. This flag takes one of the following values:

• y, yes, on, true or no value: enable overflow checks.
• n, no, off or false: disable overflow checks.

If not specified, overflow checks are enabled if debug-assertions are enabled, disabled otherwise.

panic

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

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

If not specified, the default depends on the target.

passes

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

The list must be separated by spaces.

See also the no-prepopulate-passes flag.

prefer-dynamic

By default, rustc prefers to statically link dependencies. This option will indicate that dynamic linking should be used if possible if both a static and dynamic versions of a library are available.

There is an internal algorithm for determining whether or not it is possible to statically or dynamically link with a dependency.

This flag takes one of the following values:

• y, yes, on, true or no value: prefer dynamic linking.
• n, no, off or false: prefer static linking (the default).

profile-generate

This flag allows for creating instrumented binaries that will collect profiling data for use with profile-guided optimization (PGO). The flag takes an optional argument which is the path to a directory into which the instrumented binary will emit the collected data. See the chapter on profile-guided optimization for more information.

profile-use

This flag specifies the profiling data file to be used for profile-guided optimization (PGO). The flag takes a mandatory argument which is the path to a valid .profdata file. See the chapter on profile-guided optimization for more information.

relocation-model

This option controls generation of position-independent code (PIC).

Supported values for this option are:

Primary relocation models

• static - non-relocatable code, machine instructions may use absolute addressing modes.

• pic - fully relocatable position independent code, machine instructions need to use relative addressing modes.
  Equivalent to the "uppercase" -fPIC or -fPIE options in other compilers, depending on the produced crate types.
  This is the default model for majority of supported targets.

• pie - position independent executable, relocatable code but without support for symbol interpositioning (replacing symbols by name using LD_PRELOAD and similar). Equivalent to the "uppercase" -fPIE option in other compilers. pie code cannot be linked into shared libraries (you'll get a linking error on attempt to do this).

Special relocation models

• dynamic-no-pic - relocatable external references, non-relocatable code.
  Only makes sense on Darwin and is rarely used.
  If StackOverflow tells you to use this as an opt-out of PIC or PIE, don't believe it, use -C relocation-model=static instead.
• ropi, rwpi and ropi-rwpi - relocatable code and read-only data, relocatable read-write data, and combination of both, respectively.
  Only makes sense for certain embedded ARM targets.
• default - relocation model default to the current target.
  Only makes sense as an override for some other explicitly specified relocation model previously set on the command line.

Supported values can also be discovered by running rustc --print relocation-models.

Linking effects

In addition to codegen effects, relocation-model has effects during linking.

If the relocation model is pic and the current target supports position-independent executables (PIE), the linker will be instructed (-pie) to produce one.
If the target doesn't support both position-independent and statically linked executables, then -C target-feature=+crt-static "wins" over -C relocation-model=pic, and the linker is instructed (-static) to produce a statically linked but not position-independent executable.

relro-level

This flag controls what level of RELRO (Relocation Read-Only) is enabled. RELRO is an exploit mitigation which makes the Global Offset Table (GOT) read-only.

Supported values for this option are:

• off: Dynamically linked functions are resolved lazily and the GOT is writable.
• partial: Dynamically linked functions are resolved lazily and written into the Procedure Linking Table (PLT) part of the GOT (.got.plt). The non-PLT part of the GOT (.got) is made read-only and both are moved to prevent writing from buffer overflows.
• full: Dynamically linked functions are resolved at the start of program execution and the Global Offset Table (.got/.got.plt) is populated eagerly and then made read-only. The GOT is also moved to prevent writing from buffer overflows. Full RELRO uses more memory and increases process startup time.

This flag is ignored on platforms where RELRO is not supported (targets which do not use the ELF binary format), such as Windows or macOS. Each rustc target has its own default for RELRO. rustc enables Full RELRO by default on platforms where it is supported.

remark

This flag lets you print remarks for optimization passes.

The list of passes should be separated by spaces.

all will remark on every pass.

rpath

This flag controls whether rpath is enabled. It takes one of the following values:

• y, yes, on, true or no value: enable rpath.
• n, no, off or false: disable rpath (the default).

save-temps

This flag controls whether temporary files generated during compilation are deleted once compilation finishes. It takes one of the following values:

• y, yes, on, true or no value: save temporary files.
• n, no, off or false: delete temporary files (the default).

soft-float

This option controls whether rustc generates code that emulates floating point instructions in software. It takes one of the following values:

• y, yes, on, true or no value: use soft floats.
• n, no, off or false: use hardware floats (the default).

split-debuginfo

This option controls the emission of "split debuginfo" for debug information that rustc generates. The default behavior of this option is platform-specific, and not all possible values for this option work on all platforms. Possible values are:

• off - This is the default for platforms with ELF binaries and windows-gnu (not Windows MSVC and not macOS). This typically means that DWARF debug information can be found in the final artifact in sections of the executable. This option is not supported on Windows MSVC. On macOS this options prevents the final execution of dsymutil to generate debuginfo.

• packed - This is the default for Windows MSVC and macOS. The term "packed" here means that all the debug information is packed into a separate file from the main executable. On Windows MSVC this is a *.pdb file, on macOS this is a *.dSYM folder, and on other platforms this is a *.dwp file.

• unpacked - This means that debug information will be found in separate files for each compilation unit (object file). This is not supported on Windows MSVC. On macOS this means the original object files will contain debug information. On other Unix platforms this means that *.dwo files will contain debug information.

Note that all three options are supported on Linux and Apple platforms, packed is supported on Windows-MSVC, and all other platforms support off. Attempting to use an unsupported option requires using the nightly channel with the -Z unstable-options flag.

strip

The option -C strip=val controls stripping of debuginfo and similar auxiliary data from binaries during linking.

Supported values for this option are:

• none - debuginfo and symbols are not modified.
• debuginfo - debuginfo sections and debuginfo symbols from the symbol table section are stripped at link time and are not copied to the produced binary. This should leave backtraces mostly-intact but may make using a debugger like gdb or lldb ineffectual. Prior to 1.79, this unintentionally disabled the generation of *.pdb files on MSVC, resulting in the absence of symbols.
• symbols - same as debuginfo, but the rest of the symbol table section is stripped as well, depending on platform support. On platforms which depend on this symbol table for backtraces, profiling, and similar, this can affect them so negatively as to make the trace incomprehensible. Programs which may be combined with others, such as CLI pipelines and developer tooling, or even anything which wants crash-reporting, should usually avoid -Cstrip=symbols.

Note that, at any level, removing debuginfo only necessarily impacts "friendly" introspection. -Cstrip cannot be relied on as a meaningful security or obfuscation measure, as disassemblers and decompilers can extract considerable information even in the absence of symbols.

symbol-mangling-version

This option controls the name mangling format for encoding Rust item names for the purpose of generating object code and linking.

Supported values for this option are:

• v0 — The "v0" mangling scheme.

The default, if not specified, will use a compiler-chosen default which may change in the future.

See the Symbol Mangling chapter for details on symbol mangling and the mangling format.

target-cpu

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 and the default target CPU for the current build target. Each target has a default base CPU. Special values include:

• native can be passed to use the processor of the host machine.
• generic refers to an LLVM target with minimal features but modern tuning.

target-feature

Individual targets will support different features; this flag lets you control enabling or disabling a feature. Each feature should be prefixed with a + to enable it or - to disable it.

Features from multiple -C target-feature options are combined.
Multiple features can be specified in a single option by separating them with commas - -C target-feature=+x,-y.
If some feature is specified more than once with both + and -, then values passed later override values passed earlier.
For example, -C target-feature=+x,-y,+z -Ctarget-feature=-x,+y is equivalent to -C target-feature=-x,+y,+z.

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

Using this flag is unsafe and might result in undefined runtime behavior.

See also the target_feature attribute for controlling features per-function.

This also supports the feature +crt-static and -crt-static to control static C runtime linkage.

Each target and target-cpu has a default set of enabled features.

tune-cpu

This instructs rustc to schedule code specifically for a particular processor. This does not affect the compatibility (instruction sets or ABI), but should make your code slightly more efficient on the selected CPU.

The valid options are the same as those for target-cpu. The default is None, which LLVM translates as the target-cpu.

This is an unstable option. Use -Z tune-cpu=machine to specify a value.

Due to limitations in LLVM (12.0.0-git9218f92), this option is currently effective only for x86 targets.

Jobserver

Internally, rustc may take advantage of parallelism. rustc will coordinate with the build system calling it if a GNU Make jobserver is passed in the MAKEFLAGS environment variable. Other flags may have an effect as well, such as CARGO_MAKEFLAGS. If a jobserver is not passed, then rustc will choose the number of jobs to use.

Starting with Rust 1.76.0, rustc will warn if a jobserver appears to be available but is not accessible, e.g.:

$ echo 'fn main() {}' | MAKEFLAGS=--jobserver-auth=3,4 rustc -
warning: failed to connect to jobserver from environment variable `MAKEFLAGS="--jobserver-auth=3,4"`: cannot open file descriptor 3 from the jobserver environment variable value: Bad file descriptor (os error 9)
  |
  = note: the build environment is likely misconfigured

Integration with build systems

The following subsections contain recommendations on how to integrate rustc with build systems so that the jobserver is handled appropriately.

GNU Make

When calling rustc from GNU Make, it is recommended that all rustc invocations are marked as recursive in the Makefile (by prefixing the command line with the + indicator), so that GNU Make enables the jobserver for them. For instance:

x:
	+@echo 'fn main() {}' | rustc -

In particular, GNU Make 4.3 (a widely used version as of 2024) passes a simple pipe jobserver in MAKEFLAGS even when it was not made available for the child process, which in turn means rustc will warn about it. For instance, if the + indicator is removed from the example above and GNU Make is called with e.g. make -j2, then the aforementioned warning will trigger.

For calls to rustc inside $(shell ...) inside a recursive Make, one can disable the jobserver manually by clearing the MAKEFLAGS variable, e.g.:

S := $(shell MAKEFLAGS= rustc --print sysroot)

x:
	@$(MAKE) y

y:
	@echo $(S)

CMake

CMake 3.28 supports the JOB_SERVER_AWARE option in its add_custom_target command, e.g.:

cmake_minimum_required(VERSION 3.28)
project(x)
add_custom_target(x
    JOB_SERVER_AWARE TRUE
    COMMAND echo 'fn main() {}' | rustc -
)

For earlier versions, when using CMake with the Makefile generator, one workaround is to have $(MAKE) somewhere in the command so that GNU Make treats it as a recursive Make call, e.g.:

cmake_minimum_required(VERSION 3.22)
project(x)
add_custom_target(x
    COMMAND DUMMY_VARIABLE=$(MAKE) echo 'fn main() {}' | rustc -
)

Lints

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.

Future-incompatible lints

Sometimes the compiler needs to be changed to fix an issue that can cause existing code to stop compiling. "Future-incompatible" lints are issued in these cases to give users of Rust a smooth transition to the new behavior. Initially, the compiler will continue to accept the problematic code and issue a warning. The warning has a description of the problem, a notice that this will become an error in the future, and a link to a tracking issue that provides detailed information and an opportunity for feedback. This gives users some time to fix the code to accommodate the change. After some time, the warning may become an error.

The following is an example of what a future-incompatible looks like:

warning: borrow of packed field is unsafe and requires unsafe function or block (error E0133)
  --> lint_example.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>
   = note: fields of packed structs might be misaligned: dereferencing a misaligned pointer or even just creating a misaligned reference is undefined behavior

For more information about the process and policy of future-incompatible changes, see RFC 1589.

Lint Levels

In rustc, lints are divided into six levels:

1. allow
2. expect
3. warn
4. force-warn
5. deny
6. 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.

allow

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

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.

expect

Sometimes, it can be helpful to suppress lints, but at the same time ensure that the code in question still emits them. The 'expect' level does exactly this. If the lint in question is not emitted, the unfulfilled_lint_expectation lint triggers on the expect attribute, notifying you that the expectation is no longer fulfilled.

fn main() {
    #[expect(unused_variables)]
    let unused = "Everyone ignores me";

    #[expect(unused_variables)] // `unused_variables` lint is not emitted
    let used = "I'm useful";    // the expectation is therefore unfulfilled
    println!("The `used` value is equal to: {:?}", used);
}

This will produce the following warning:

warning: this lint expectation is unfulfilled
 --> src/main.rs:7:14
  |
7 |     #[expect(unused_variables)]
  |              ^^^^^^^^^^^^^^^^
  |
  = note: `#[warn(unfulfilled_lint_expectations)]` on by default

This level can only be defined via the #[expect] attribute, there is no equivalent flag. Lints with the special 'force-warn' level will still be emitted as usual.

warn

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

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

force-warn

'force-warn' is a special lint level. It's the same as 'warn' in that a lint at this level will produce a warning, but unlike the 'warn' level, the 'force-warn' level cannot be overridden. If a lint is set to 'force-warn', it is guaranteed to warn: no more, no less. This is true even if the overall lint level is capped via cap-lints.

deny

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

'forbid' is a special lint level that fills the same role for 'deny' that 'force-warn' does for 'warn'. 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.

Configuring warning levels

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.

Via compiler flag

The -A, -W, --force-warn -D, and -F flags let you turn one or more lints into allowed, warning, force-warn, 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 five flags together:

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

The order of these command line arguments is taken into account. The following allows the unused-variables lint, because it is the last argument for that lint:

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

You can make use of this behavior by overriding the level of one specific lint out of a group of lints. The following example denies all the lints in the unused group, but explicitly allows the unused-variables lint in that group (forbid still trumps everything regardless of ordering):

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

Since force-warn and forbid cannot be overridden, setting one of them will prevent any later level for the same lint from taking effect.

Via an attribute

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() {}
  | ^^^^^^^^^^^^

warn, allow, deny, and forbid all work this way. There is no way to set a lint to force-warn using an attribute.

You can also pass in multiple lints per attribute:

#![warn(missing_docs, unused_variables)]

pub fn foo() {}

And use multiple attributes together:

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

pub fn foo() {}

All lint attributes support an additional reason parameter, to give context why a certain attribute was added. This reason will be displayed as part of the lint message, if the lint is emitted at the defined level.

use std::path::PathBuf;
pub fn get_path() -> PathBuf {
    #[allow(unused_mut, reason = "this is only modified on some platforms")]
    let mut file_name = PathBuf::from("git");
    #[cfg(target_os = "windows")]
    file_name.set_extension("exe");
    file_name
}

Capping lints

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.

Lint Groups

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:

{{groups-table}}

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.

Lint Listing

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.

Allowed-by-default Lints

This file is auto-generated by the lint-docs script.

Warn-by-default Lints

This file is auto-generated by the lint-docs script.

Deny-by-default Lints

This file is auto-generated by the lint-docs script.

JSON Output

This chapter documents the JSON structures emitted by rustc. JSON may be enabled with the --error-format=json flag. Additional options may be specified with the --json flag which can change which messages are generated, and the format of the messages.

JSON messages are emitted one per line to stderr.

If parsing the output with Rust, the cargo_metadata crate provides some support for parsing the messages.

Each type of message has a $message_type field which can be used to distinguish the different formats. When parsing, care should be taken to be forwards-compatible with future changes to the format. Optional values may be null. New fields may be added. Enumerated fields like "level" or "suggestion_applicability" may add new values.

Diagnostics

Diagnostic messages provide errors or possible concerns generated during compilation. rustc provides detailed information about where the diagnostic originates, along with hints and suggestions.

Diagnostics are arranged in a parent/child relationship where the parent diagnostic value is the core of the diagnostic, and the attached children provide additional context, help, and information.

Diagnostics have the following format:

{
    /* Type of this message */
    "$message_type": "diagnostic",
    /* The primary message. */
    "message": "unused variable: `x`",
    /* The diagnostic code.
       Some messages may set this value to null.
    */
    "code": {
        /* A unique string identifying which diagnostic triggered. */
        "code": "unused_variables",
        /* An optional string explaining more detail about the diagnostic code. */
        "explanation": null
    },
    /* The severity of the diagnostic.
       Values may be:
       - "error": A fatal error that prevents compilation.
       - "warning": A possible error or concern.
       - "note": Additional information or context about the diagnostic.
       - "help": A suggestion on how to resolve the diagnostic.
       - "failure-note": A note attached to the message for further information.
       - "error: internal compiler error": Indicates a bug within the compiler.
    */
    "level": "warning",
    /* An array of source code locations to point out specific details about
       where the diagnostic originates from. This may be empty, for example
       for some global messages, or child messages attached to a parent.

       Character offsets are offsets of Unicode Scalar Values.
    */
    "spans": [
        {
            /* The file where the span is located.
               Note that this path may not exist. For example, if the path
               points to the standard library, and the rust src is not
               available in the sysroot, then it may point to a nonexistent
               file. Beware that this may also point to the source of an
               external crate.
            */
            "file_name": "lib.rs",
            /* The byte offset where the span starts (0-based, inclusive). */
            "byte_start": 21,
            /* The byte offset where the span ends (0-based, exclusive). */
            "byte_end": 22,
            /* The first line number of the span (1-based, inclusive). */
            "line_start": 2,
            /* The last line number of the span (1-based, inclusive). */
            "line_end": 2,
            /* The first character offset of the line_start (1-based, inclusive). */
            "column_start": 9,
            /* The last character offset of the line_end (1-based, exclusive). */
            "column_end": 10,
            /* Whether or not this is the "primary" span.

               This indicates that this span is the focal point of the
               diagnostic.

               There are rare cases where multiple spans may be marked as
               primary. For example, "immutable borrow occurs here" and
               "mutable borrow ends here" can be two separate primary spans.

               The top (parent) message should always have at least one
               primary span, unless it has zero spans. Child messages may have
               zero or more primary spans.
            */
            "is_primary": true,
            /* An array of objects showing the original source code for this
               span. This shows the entire lines of text where the span is
               located. A span across multiple lines will have a separate
               value for each line.
            */
            "text": [
                {
                    /* The entire line of the original source code. */
                    "text": "    let x = 123;",
                    /* The first character offset of the line of
                       where the span covers this line (1-based, inclusive). */
                    "highlight_start": 9,
                    /* The last character offset of the line of
                       where the span covers this line (1-based, exclusive). */
                    "highlight_end": 10
                }
            ],
            /* An optional message to display at this span location.
               This is typically null for primary spans.
            */
            "label": null,
            /* An optional string of a suggested replacement for this span to
               solve the issue. Tools may try to replace the contents of the
               span with this text.
            */
            "suggested_replacement": null,
            /* An optional string that indicates the confidence of the
               "suggested_replacement". Tools may use this value to determine
               whether or not suggestions should be automatically applied.

               Possible values may be:
               - "MachineApplicable": The suggestion is definitely what the
                 user intended. This suggestion should be automatically
                 applied.
               - "MaybeIncorrect": The suggestion may be what the user
                 intended, but it is uncertain. The suggestion should result
                 in valid Rust code if it is applied.
               - "HasPlaceholders": The suggestion contains placeholders like
                 `(...)`. The suggestion cannot be applied automatically
                 because it will not result in valid Rust code. The user will
                 need to fill in the placeholders.
               - "Unspecified": The applicability of the suggestion is unknown.
            */
            "suggestion_applicability": null,
            /* An optional object indicating the expansion of a macro within
               this span.

               If a message occurs within a macro invocation, this object will
               provide details of where within the macro expansion the message
               is located.
            */
            "expansion": {
                /* The span of the macro invocation.
                   Uses the same span definition as the "spans" array.
                */
                "span": {/*...*/}
                /* Name of the macro, such as "foo!" or "#[derive(Eq)]". */
                "macro_decl_name": "some_macro!",
                /* Optional span where the relevant part of the macro is
                  defined. */
                "def_site_span": {/*...*/},
            }
        }
    ],
    /* Array of attached diagnostic messages.
       This is an array of objects using the same format as the parent
       message. Children are not nested (children do not themselves
       contain "children" definitions).
    */
    "children": [
        {
            "message": "`#[warn(unused_variables)]` on by default",
            "code": null,
            "level": "note",
            "spans": [],
            "children": [],
            "rendered": null
        },
        {
            "message": "if this is intentional, prefix it with an underscore",
            "code": null,
            "level": "help",
            "spans": [
                {
                    "file_name": "lib.rs",
                    "byte_start": 21,
                    "byte_end": 22,
                    "line_start": 2,
                    "line_end": 2,
                    "column_start": 9,
                    "column_end": 10,
                    "is_primary": true,
                    "text": [
                        {
                            "text": "    let x = 123;",
                            "highlight_start": 9,
                            "highlight_end": 10
                        }
                    ],
                    "label": null,
                    "suggested_replacement": "_x",
                    "suggestion_applicability": "MachineApplicable",
                    "expansion": null
                }
            ],
            "children": [],
            "rendered": null
        }
    ],
    /* Optional string of the rendered version of the diagnostic as displayed
       by rustc. Note that this may be influenced by the `--json` flag.
    */
    "rendered": "warning: unused variable: `x`\n --> lib.rs:2:9\n  |\n2 |     let x = 123;\n  |         ^ help: if this is intentional, prefix it with an underscore: `_x`\n  |\n  = note: `#[warn(unused_variables)]` on by default\n\n"
}

Artifact notifications

Artifact notifications are emitted when the --json=artifacts flag is used. They indicate that a file artifact has been saved to disk. More information about emit kinds may be found in the --emit flag documentation. Notifications can contain more than one file for each type, for example when using multiple codegen units.

{
    /* Type of this message */
    "$message_type": "artifact",
    /* The filename that was generated. */
    "artifact": "libfoo.rlib",
    /* The kind of artifact that was generated. Possible values:
       - "link": The generated crate as specified by the crate-type.
       - "dep-info": The `.d` file with dependency information in a Makefile-like syntax.
       - "metadata": The Rust `.rmeta` file containing metadata about the crate.
       - "asm": The `.s` file with generated assembly
       - "llvm-ir": The `.ll` file with generated textual LLVM IR
       - "llvm-bc": The `.bc` file with generated LLVM bitcode
       - "mir": The `.mir` file with rustc's mid-level intermediate representation.
       - "obj": The `.o` file with generated native object code
    */
    "emit": "link"
}

Future-incompatible reports

If the --json=future-incompat flag is used, then a separate JSON structure will be emitted if the crate may stop compiling in the future. This contains diagnostic information about the particular warnings that may be turned into a hard error in the future. This will include the diagnostic information, even if the diagnostics have been suppressed (such as with an #[allow] attribute or the --cap-lints option).

{
    /* Type of this message */
    "$message_type": "future_incompat",
    /* An array of objects describing a warning that will become a hard error
       in the future.
    */
    "future_incompat_report":
    [
        {
            /* A diagnostic structure as defined in
               https://doc.rust-lang.org/rustc/json.html#diagnostics
            */
            "diagnostic": {...},
        }
    ]
}

Unused Dependency Notifications

The options --json=unused-externs and --json=unused-externs-silent in conjunction with the unused-crate-dependencies lint will emit JSON structures reporting any crate dependencies (specified with --extern) which never had any symbols referenced. These are intended to be consumed by the build system which can then emit diagnostics telling the user to remove the unused dependencies from Cargo.toml (or whatever build-system file defines dependencies).

The JSON structure is:

{
    "lint_level": "deny", /* Level of the warning */
    "unused_names": [
        "foo"  /* Names of unused crates, as specified with --extern foo=libfoo.rlib */
    ],
}

The warn/deny/forbid lint level (as defined either on the command line or in the source) dictates the lint_level in the JSON. With unused-externs, a deny or forbid level diagnostic will also cause rustc to exit with a failure exit code.

unused-externs-silent will report the diagnostic the same way, but will not cause rustc to exit with failure - it's up to the consumer to flag failure appropriately. (This is needed by Cargo which shares the same dependencies across multiple build targets, so it should only report an unused dependency if its not used by any of the targets.)

Tests

rustc has a built-in facility for building and running tests for a crate. More information about writing and running tests may be found in the Testing Chapter of the Rust Programming Language book.

Tests are written as free functions with the #[test] attribute. For example:

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

Tests "pass" if they return without an error. They "fail" if they panic, or return a type such as Result that implements the Termination trait with a non-zero value.

By passing the --test option to rustc, the compiler will build the crate in a special mode to construct an executable that will run the tests in the crate. The --test flag will make the following changes:

• The crate will be built as a bin crate type, forcing it to be an executable.
• Links the executable with libtest, the test harness that is part of the standard library, which handles running the tests.
• Synthesizes a main function which will process command-line arguments and run the tests. This new main function will replace any existing main function as the entry point of the executable, though the existing main will still be compiled.
• Enables the test cfg option, which allows your code to use conditional compilation to detect if it is being built as a test.
• Enables building of functions annotated with the test and bench attributes, which will be run by the test harness.

After the executable is created, you can run it to execute the tests and receive a report on what passes and fails. If you are using Cargo to manage your project, it has a built-in cargo test command which handles all of this automatically. An example of the output looks like this:

running 4 tests
test it_works ... ok
test check_valid_args ... ok
test invalid_characters ... ok
test walks_the_dog ... ok

test result: ok. 4 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

Note: Tests must be built with the unwind panic strategy. This is because all tests run in the same process, and they are intended to catch panics, which is not possible with the abort strategy. See the unstable -Z panic-abort-tests option for experimental support of the abort strategy by spawning tests in separate processes.

Test attributes

Tests are indicated using attributes on free functions. The following attributes are used for testing, see the linked documentation for more details:

• #[test] — Indicates a function is a test to be run.
• #[bench] — Indicates a function is a benchmark to be run. Benchmarks are currently unstable and only available in the nightly channel, see the unstable docs for more details.
• #[should_panic] — Indicates that the test function will only pass if the function panics.
• #[ignore] — Indicates that the test function will be compiled, but not run by default. See the --ignored and --include-ignored options to run these tests.

CLI arguments

The libtest harness has several command-line arguments to control its behavior.

Note: When running with cargo test, the libtest CLI arguments must be passed after the -- argument to differentiate between flags for Cargo and those for the harness. For example: cargo test -- --nocapture

Filters

Positional arguments (those without a - prefix) are treated as filters which will only run tests whose name matches one of those strings. The filter will match any substring found in the full path of the test function. For example, if the test function it_works is located in the module utils::paths::tests, then any of the filters works, path, utils::, or utils::paths::tests::it_works will match that test.

See Selection options for more options to control which tests are run.

Action options

The following options perform different actions other than running tests.

--list

Prints a list of all tests and benchmarks. Does not run any of the tests. Filters can be used to list only matching tests.

-h, --help

Displays usage information and command-line options.

Selection options

The following options change how tests are selected.

--test

This is the default mode where all tests will be run as well as running all benchmarks with only a single iteration (to ensure the benchmark works, without taking the time to actually perform benchmarking). This can be combined with the --bench flag to run both tests and perform full benchmarking.

--bench

This runs in a mode where tests are ignored, and only runs benchmarks. This can be combined with --test to run both benchmarks and tests.

--exact

This forces filters to match the full path of the test exactly. For example, if the test it_works is in the module utils::paths::tests, then only the string utils::paths::tests::it_works will match that test.

--skip FILTER

Skips any tests whose name contains the given FILTER string. This flag may be passed multiple times.

--ignored

Runs only tests that are marked with the ignore attribute.

--include-ignored

Runs both ignored and non-ignored tests.

--exclude-should-panic

Excludes tests marked with the should_panic attribute.

⚠️ 🚧 This option is unstable, and requires the -Z unstable-options flag. See tracking issue #82348 for more information.

Execution options

The following options affect how tests are executed.

--test-threads NUM_THREADS

Sets the number of threads to use for running tests in parallel. By default, uses the amount of concurrency available on the hardware as indicated by available_parallelism.

This can also be specified with the RUST_TEST_THREADS environment variable.

--force-run-in-process

Forces the tests to run in a single process when using the abort panic strategy.

⚠️ 🚧 This only works with the unstable -Z panic-abort-tests option, and requires the -Z unstable-options flag. See tracking issue #67650 for more information.

--ensure-time

⚠️ 🚧 This option is unstable, and requires the -Z unstable-options flag. See tracking issue #64888 and the unstable docs for more information.

--shuffle

Runs the tests in random order, as opposed to the default alphabetical order.

This may also be specified by setting the RUST_TEST_SHUFFLE environment variable to anything but 0.

The random number generator seed that is output can be passed to --shuffle-seed to run the tests in the same order again.

Note that --shuffle does not affect whether the tests are run in parallel. To run the tests in random order sequentially, use --shuffle --test-threads 1.

⚠️ 🚧 This option is unstable, and requires the -Z unstable-options flag. See tracking issue #89583 for more information.

--shuffle-seed SEED

Like --shuffle, but seeds the random number generator with SEED. Thus, calling the test harness with --shuffle-seed SEED twice runs the tests in the same order both times.

SEED is any 64-bit unsigned integer, for example, one produced by --shuffle.

This can also be specified with the RUST_TEST_SHUFFLE_SEED environment variable.

⚠️ 🚧 This option is unstable, and requires the -Z unstable-options flag. See tracking issue #89583 for more information.

Output options

The following options affect the output behavior.

-q, --quiet

Displays one character per test instead of one line per test. This is an alias for --format=terse.

--nocapture

Does not capture the stdout and stderr of the test, and allows tests to print to the console. Usually the output is captured, and only displayed if the test fails.

This may also be specified by setting the RUST_TEST_NOCAPTURE environment variable to anything but 0.

--show-output

Displays the stdout and stderr of successful tests after all tests have run.

Contrast this with --nocapture which allows tests to print while they are running, which can cause interleaved output if there are multiple tests running in parallel, --show-output ensures the output is contiguous, but requires waiting for all tests to finish.

--color COLOR

Control when colored terminal output is used. Valid options:

• auto: Colorize if stdout is a tty and --nocapture is not used. This is the default.
• always: Always colorize the output.
• never: Never colorize the output.

--format FORMAT

Controls the format of the output. Valid options:

• pretty: This is the default format, with one line per test.
• terse: Displays only a single character per test. --quiet is an alias for this option.
• json: Emits JSON objects, one per line. ⚠️ 🚧 This option is unstable, and requires the -Z unstable-options flag. See tracking issue #49359 for more information.

--logfile PATH

Writes the results of the tests to the given file.

This option is deprecated.

--report-time

⚠️ 🚧 This option is unstable, and requires the -Z unstable-options flag. See tracking issue #64888 and the unstable docs for more information.

Unstable options

Some CLI options are added in an "unstable" state, where they are intended for experimentation and testing to determine if the option works correctly, has the right design, and is useful. The option may not work correctly, break, or change at any time. To signal that you acknowledge that you are using an unstable option, they require passing the -Z unstable-options command-line flag.

Benchmarks

The libtest harness supports running benchmarks for functions annotated with the #[bench] attribute. Benchmarks are currently unstable, and only available on the nightly channel. More information may be found in the unstable book.

Custom test frameworks

Experimental support for using custom test harnesses is available on the nightly channel. See tracking issue #50297 and the custom_test_frameworks documentation for more information.

Platform Support

Support for different platforms ("targets") are organized into three tiers, each with a different set of guarantees. For more information on the policies for targets at each tier, see the Target Tier Policy.

Targets are identified by their "target triple" which is the string to inform the compiler what kind of output should be produced.

Component availability is tracked here.

Tier 1 with Host Tools

Tier 1 targets can be thought of as "guaranteed to work". The Rust project builds official binary releases for each tier 1 target, and automated testing ensures that each tier 1 target builds and passes tests after each change.

Tier 1 targets with host tools additionally support running tools like rustc and cargo natively on the target, and automated testing ensures that tests pass for the host tools as well. This allows the target to be used as a development platform, not just a compilation target. For the full requirements, see Tier 1 with Host Tools in the Target Tier Policy.

All tier 1 targets with host tools support the full standard library.

Tier 1

Tier 1 targets can be thought of as "guaranteed to work". The Rust project builds official binary releases for each tier 1 target, and automated testing ensures that each tier 1 target builds and passes tests after each change. For the full requirements, see Tier 1 target policy in the Target Tier Policy.

At this time, all Tier 1 targets are Tier 1 with Host Tools.

Tier 2 with Host Tools

Tier 2 targets can be thought of as "guaranteed to build". The Rust project builds official binary releases of the standard library (or, in some cases, only the core library) for each tier 2 target, and automated builds ensure that each tier 2 target can be used as build target after each change. Automated tests are not always run so it's not guaranteed to produce a working build, but tier 2 targets often work to quite a good degree and patches are always welcome!

Tier 2 target-specific code is not closely scrutinized by Rust team(s) when modifications are made. Bugs are possible in all code, but the level of quality control for these targets is likely to be lower. See library team policy for details on the review practices for standard library code.

Tier 2 targets with host tools additionally support running tools like rustc and cargo natively on the target, and automated builds ensure that the host tools build as well. This allows the target to be used as a development platform, not just a compilation target. For the full requirements, see Tier 2 with Host Tools in the Target Tier Policy.

All tier 2 targets with host tools support the full standard library.

NOTE: The rust-docs component is not usually built for tier 2 targets, so Rustup may install the documentation for a similar tier 1 target instead.

Tier 2 without Host Tools

Tier 2 targets can be thought of as "guaranteed to build". The Rust project builds official binary releases of the standard library (or, in some cases, only the core library) for each tier 2 target, and automated builds ensure that each tier 2 target can be used as build target after each change. Automated tests are not always run so it's not guaranteed to produce a working build, but tier 2 targets often work to quite a good degree and patches are always welcome! For the full requirements, see Tier 2 target policy in the Target Tier Policy.

The std column in the table below has the following meanings:

• ✓ indicates the full standard library is available.
• * indicates the target only supports no_std development.
• ? indicates the standard library support is a work-in-progress.

Tier 2 target-specific code is not closely scrutinized by Rust team(s) when modifications are made. Bugs are possible in all code, but the level of quality control for these targets is likely to be lower. See library team policy for details on the review practices for standard library code.

NOTE: The rust-docs component is not usually built for tier 2 targets, so Rustup may install the documentation for a similar tier 1 target instead.

Tier 3

Tier 3 targets are those which the Rust codebase has support for, but which the Rust project does not build or test automatically, so they may or may not work. Official builds are not available. For the full requirements, see Tier 3 target policy in the Target Tier Policy.

The std column in the table below has the following meanings:

• ✓ indicates the full standard library is available.
• * indicates the target only supports no_std development.
• ? indicates the standard library support is unknown or a work-in-progress.

Tier 3 target-specific code is not closely scrutinized by Rust team(s) when modifications are made. Bugs are possible in all code, but the level of quality control for these targets is likely to be lower. See library team policy for details on the review practices for standard library code.

The host column indicates whether the codebase includes support for building host tools.

Target Tier Policy

Table of Contents

• General
• Adding a new target
• Tier 3 target policy
• Tier 2 target policy
  • Tier 2 with host tools
• Tier 1 target policy
  • Tier 1 with host tools

General

Rust provides three tiers of target support:

• Rust provides no guarantees about tier 3 targets; they exist in the codebase, but may or may not build.
• Rust's continuous integration checks that tier 2 targets will always build, but they may or may not pass tests.
• Rust's continuous integration checks that tier 1 targets will always build and pass tests.

Adding a new tier 3 target imposes minimal requirements; we focus primarily on avoiding disruption to other ongoing Rust development.

Tier 2 and tier 1 targets place work on Rust project developers as a whole, to avoid breaking the target. The broader Rust community may also feel more inclined to support higher-tier targets in their crates (though they are not obligated to do so). Thus, these tiers require commensurate and ongoing efforts from the maintainers of the target, to demonstrate value and to minimize any disruptions to ongoing Rust development.

This policy defines the requirements for accepting a proposed target at a given level of support.

Each tier builds on all the requirements from the previous tier, unless overridden by a stronger requirement. Targets at tier 2 and tier 1 may also provide host tools (such as rustc and cargo); each of those tiers includes a set of supplementary requirements that must be met if supplying host tools for the target. A target at tier 2 or tier 1 is not required to supply host tools, but if it does, it must meet the corresponding additional requirements for host tools.

The policy for each tier also documents the Rust governance teams that must approve the addition of any target at that tier. Those teams are responsible for reviewing and evaluating the target, based on these requirements and their own judgment. Those teams may apply additional requirements, including subjective requirements, such as to deal with issues not foreseen by this policy. (Such requirements may subsequently motivate additions to this policy.)

While these criteria attempt to document the policy, that policy still involves human judgment. Targets must fulfill the spirit of the requirements as well, as determined by the judgment of the approving teams. Reviewers and team members evaluating targets and target-specific patches should always use their own best judgment regarding the quality of work, and the suitability of a target for the Rust project. Neither this policy nor any decisions made regarding targets shall create any binding agreement or estoppel by any party.

Before filing an issue or pull request (PR) to introduce or promote a target, the target should already meet the corresponding tier requirements. This does not preclude an existing target's maintainers using issues (on the Rust repository or otherwise) to track requirements that have not yet been met, as appropriate; however, before officially proposing the introduction or promotion of a target, it should meet all of the necessary requirements. A target proposal must quote the corresponding requirements verbatim and respond to them as part of explaining how the target meets those requirements. (For the requirements that simply state that the target or the target developers must not do something, it suffices to acknowledge the requirement.)

For a list of all supported targets and their corresponding tiers ("tier 3", "tier 2", "tier 2 with host tools", "tier 1", or "tier 1 with host tools"), see platform support.

Several parts of this policy require providing target-specific documentation. Such documentation should typically appear in a subdirectory of the platform-support section of this rustc manual, with a link from the target's entry in platform support. Use TEMPLATE.md as a base, and see other documentation in that directory for examples.

Note that a target must have already received approval for the next lower tier, and spent a reasonable amount of time at that tier, before making a proposal for promotion to the next higher tier; this is true even if a target meets the requirements for several tiers at once. This policy leaves the precise interpretation of "reasonable amount of time" up to the approving teams; those teams may scale the amount of time required based on their confidence in the target and its demonstrated track record at its current tier. At a minimum, multiple stable releases of Rust should typically occur between promotions of a target.

The availability or tier of a target in stable Rust is not a hard stability guarantee about the future availability or tier of that target. Higher-level target tiers are an increasing commitment to the support of a target, and we will take that commitment and potential disruptions into account when evaluating the potential demotion or removal of a target that has been part of a stable release. The promotion or demotion of a target will not generally affect existing stable releases, only current development and future releases.

In this policy, the words "must" and "must not" specify absolute requirements that a target must meet to qualify for a tier. The words "should" and "should not" specify requirements that apply in almost all cases, but for which the approving teams may grant an exception for good reason. The word "may" indicates something entirely optional, and does not indicate guidance or recommendations. This language is based on IETF RFC 2119.

Adding a new target

New targets typically start as Tier 3 and then can be promoted later. To propose addition of a new target, open a pull request on rust-lang/rust:

• Copy the Tier 3 target policy to the description and fill it out, see example.
• Add a new description for the target in src/doc/rustc/src/platform-support using the template.
• Add the target to the SUMMARY.md (allows wildcards) and platform-support.md (must name all targets verbatim). Link to the created description page.
• Ensure the pull request is assigned to a member of the Rust compiler team by commenting:

  r? compiler
  

See also the documentation in the rustc-dev-guide on adding a new target to rustc.

Note that adding a new target that wants to support std would transitively require cc and libc support. However, these would like to know about the target from rustc as well. To break this cycle, you are strongly encouraged to add a minimal #![no_core] target spec first to teach rustc about the target's existence, and add std support as a follow-up once you've added support for the target in cc and libc.

Tier 3 target policy

At this tier, the Rust project provides no official support for a target, so we place minimal requirements on the introduction of targets.

A proposed new tier 3 target must be reviewed and approved by a member of the compiler team based on these requirements. The reviewer may choose to gauge broader compiler team consensus via a Major Change Proposal (MCP).

A proposed target or target-specific patch that substantially changes code shared with other targets (not just target-specific code) must be reviewed and approved by the appropriate team for that shared code before acceptance.

• A tier 3 target must have a designated developer or developers (the "target maintainers") on record to be CCed when issues arise regarding the target. (The mechanism to track and CC such developers may evolve over time.)
• Targets must use naming consistent with any existing targets; for instance, a target for the same CPU or OS as an existing Rust target should use the same name for that CPU or OS. Targets should normally use the same names and naming conventions as used elsewhere in the broader ecosystem beyond Rust (such as in other toolchains), unless they have a very good reason to diverge. Changing the name of a target can be highly disruptive, especially once the target reaches a higher tier, so getting the name right is important even for a tier 3 target.
  • Target names should not introduce undue confusion or ambiguity unless absolutely necessary to maintain ecosystem compatibility. For example, if the name of the target makes people extremely likely to form incorrect beliefs about what it targets, the name should be changed or augmented to disambiguate it.
  • If possible, use only letters, numbers, dashes and underscores for the name. Periods (.) are known to cause issues in Cargo.
• Tier 3 targets may have unusual requirements to build or use, but must not create legal issues or impose onerous legal terms for the Rust project or for Rust developers or users.
  • The target must not introduce license incompatibilities.
  • Anything added to the Rust repository must be under the standard Rust license (MIT OR Apache-2.0).
  • The target must not cause the Rust tools or libraries built for any other host (even when supporting cross-compilation to the target) to depend on any new dependency less permissive than the Rust licensing policy. This applies whether the dependency is a Rust crate that would require adding new license exceptions (as specified by the tidy tool in the rust-lang/rust repository), or whether the dependency is a native library or binary. In other words, the introduction of the target must not cause a user installing or running a version of Rust or the Rust tools to be subject to any new license requirements.
  • Compiling, linking, and emitting functional binaries, libraries, or other code for the target (whether hosted on the target itself or cross-compiling from another target) must not depend on proprietary (non-FOSS) libraries. Host tools built for the target itself may depend on the ordinary runtime libraries supplied by the platform and commonly used by other applications built for the target, but those libraries must not be required for code generation for the target; cross-compilation to the target must not require such libraries at all. For instance, rustc built for the target may depend on a common proprietary C runtime library or console output library, but must not depend on a proprietary code generation library or code optimization library. Rust's license permits such combinations, but the Rust project has no interest in maintaining such combinations within the scope of Rust itself, even at tier 3.
  • "onerous" here is an intentionally subjective term. At a minimum, "onerous" legal/licensing terms include but are not limited to: non-disclosure requirements, non-compete requirements, contributor license agreements (CLAs) or equivalent, "non-commercial"/"research-only"/etc terms, requirements conditional on the employer or employment of any particular Rust developers, revocable terms, any requirements that create liability for the Rust project or its developers or users, or any requirements that adversely affect the livelihood or prospects of the Rust project or its developers or users.
• Neither this policy nor any decisions made regarding targets shall create any binding agreement or estoppel by any party. If any member of an approving Rust team serves as one of the maintainers of a target, or has any legal or employment requirement (explicit or implicit) that might affect their decisions regarding a target, they must recuse themselves from any approval decisions regarding the target's tier status, though they may otherwise participate in discussions.
  • This requirement does not prevent part or all of this policy from being cited in an explicit contract or work agreement (e.g. to implement or maintain support for a target). This requirement exists to ensure that a developer or team responsible for reviewing and approving a target does not face any legal threats or obligations that would prevent them from freely exercising their judgment in such approval, even if such judgment involves subjective matters or goes beyond the letter of these requirements.
• Tier 3 targets should attempt to implement as much of the standard libraries as possible and appropriate (core for most targets, alloc for targets that can support dynamic memory allocation, std for targets with an operating system or equivalent layer of system-provided functionality), but may leave some code unimplemented (either unavailable or stubbed out as appropriate), whether because the target makes it impossible to implement or challenging to implement. The authors of pull requests are not obligated to avoid calling any portions of the standard library on the basis of a tier 3 target not implementing those portions.
• The target must provide documentation for the Rust community explaining how to build for the target, using cross-compilation if possible. If the target supports running binaries, or running tests (even if they do not pass), the documentation must explain how to run such binaries or tests for the target, using emulation if possible or dedicated hardware if necessary.
• Tier 3 targets must not impose burden on the authors of pull requests, or other developers in the community, to maintain the target. In particular, do not post comments (automated or manual) on a PR that derail or suggest a block on the PR based on a tier 3 target. Do not send automated messages or notifications (via any medium, including via @) to a PR author or others involved with a PR regarding a tier 3 target, unless they have opted into such messages.
  • Backlinks such as those generated by the issue/PR tracker when linking to an issue or PR are not considered a violation of this policy, within reason. However, such messages (even on a separate repository) must not generate notifications to anyone involved with a PR who has not requested such notifications.
• Patches adding or updating tier 3 targets must not break any existing tier 2 or tier 1 target, and must not knowingly break another tier 3 target without approval of either the compiler team or the maintainers of the other tier 3 target.
  • In particular, this may come up when working on closely related targets, such as variations of the same architecture with different features. Avoid introducing unconditional uses of features that another variation of the target may not have; use conditional compilation or runtime detection, as appropriate, to let each target run code supported by that target.
• Tier 3 targets must be able to produce assembly using at least one of rustc's supported backends from any host target. (Having support in a fork of the backend is not sufficient, it must be upstream.)

If a tier 3 target stops meeting these requirements, or the target maintainers no longer have interest or time, or the target shows no signs of activity and has not built for some time, or removing the target would improve the quality of the Rust codebase, we may post a PR to remove it; any such PR will be CCed to the target maintainers (and potentially other people who have previously worked on the target), to check potential interest in improving the situation.

Tier 2 target policy

At this tier, the Rust project guarantees that a target builds, and will reject patches that fail to build on a target. Thus, we place requirements that ensure the target will not block forward progress of the Rust project.

A proposed new tier 2 target must be reviewed and approved by the compiler team based on these requirements. Such review and approval may occur via a Major Change Proposal (MCP).

In addition, the infrastructure team must approve the integration of the target into Continuous Integration (CI), and the tier 2 CI-related requirements. This review and approval may take place in a PR adding the target to CI, or simply by an infrastructure team member reporting the outcome of a team discussion.

• A tier 2 target must have value to people other than its maintainers. (It may still be a niche target, but it must not be exclusively useful for an inherently closed group.)
• A tier 2 target must have a designated team of developers (the "target maintainers") available to consult on target-specific build-breaking issues, or if necessary to develop target-specific language or library implementation details. This team must have at least 2 developers.
  • The target maintainers should not only fix target-specific issues, but should use any such issue as an opportunity to educate the Rust community about portability to their target, and enhance documentation of the target.
• The target must not place undue burden on Rust developers not specifically concerned with that target. Rust developers are expected to not gratuitously break a tier 2 target, but are not expected to become experts in every tier 2 target, and are not expected to provide target-specific implementations for every tier 2 target.
• The target must provide documentation for the Rust community explaining how to build for the target using cross-compilation, and explaining how to run tests for the target. If at all possible, this documentation should show how to run Rust programs and tests for the target using emulation, to allow anyone to do so. If the target cannot be feasibly emulated, the documentation should explain how to obtain and work with physical hardware, cloud systems, or equivalent.
• The target must document its baseline expectations for the features or versions of CPUs, operating systems, libraries, runtime environments, and similar.
• If introducing a new tier 2 or higher target that is identical to an existing Rust target except for the baseline expectations for the features or versions of CPUs, operating systems, libraries, runtime environments, and similar, then the proposed target must document to the satisfaction of the approving teams why the specific difference in baseline expectations provides sufficient value to justify a separate target.
  • Note that in some cases, based on the usage of existing targets within the Rust community, Rust developers or a target's maintainers may wish to modify the baseline expectations of a target, or split an existing target into multiple targets with different baseline expectations. A proposal to do so will be treated similarly to the analogous promotion, demotion, or removal of a target, according to this policy, with the same team approvals required.
    • For instance, if an OS version has become obsolete and unsupported, a target for that OS may raise its baseline expectations for OS version (treated as though removing a target corresponding to the older versions), or a target for that OS may split out support for older OS versions into a lower-tier target (treated as though demoting a target corresponding to the older versions, and requiring justification for a new target at a lower tier for the older OS versions).
• Tier 2 targets must not leave any significant portions of core or the standard library unimplemented or stubbed out, unless they cannot possibly be supported on the target.
  • The right approach to handling a missing feature from a target may depend on whether the target seems likely to develop the feature in the future. In some cases, a target may be co-developed along with Rust support, and Rust may gain new features on the target as that target gains the capabilities to support those features.
  • As an exception, a target identical to an existing tier 1 target except for lower baseline expectations for the OS, CPU, or similar, may propose to qualify as tier 2 (but not higher) without support for std if the target will primarily be used in no_std applications, to reduce the support burden for the standard library. In this case, evaluation of the proposed target's value will take this limitation into account.
• The code generation backend for the target should not have deficiencies that invalidate Rust safety properties, as evaluated by the Rust compiler team. (This requirement does not apply to arbitrary security enhancements or mitigations provided by code generation backends, only to those properties needed to ensure safe Rust code cannot cause undefined behavior or other unsoundness.) If this requirement does not hold, the target must clearly and prominently document any such limitations as part of the target's entry in the target tier list, and ideally also via a failing test in the testsuite. The Rust compiler team must be satisfied with the balance between these limitations and the difficulty of implementing the necessary features.
  • For example, if Rust relies on a specific code generation feature to ensure that safe code cannot overflow the stack, the code generation for the target should support that feature.
  • If the Rust compiler introduces new safety properties (such as via new capabilities of a compiler backend), the Rust compiler team will determine if they consider those new safety properties a best-effort improvement for specific targets, or a required property for all Rust targets. In the latter case, the compiler team may require the maintainers of existing targets to either implement and confirm support for the property or update the target tier list with documentation of the missing property.
• If the target supports C code, and the target has an interoperable calling convention for C code, the Rust target must support that C calling convention for the platform via extern "C". The C calling convention does not need to be the default Rust calling convention for the target, however.
• The target must build reliably in CI, for all components that Rust's CI considers mandatory.
• The approving teams may additionally require that a subset of tests pass in CI, such as enough to build a functional "hello world" program, ./x.py test --no-run, or equivalent "smoke tests". In particular, this requirement may apply if the target builds host tools, or if the tests in question provide substantial value via early detection of critical problems.
• Building the target in CI must not take substantially longer than the current slowest target in CI, and should not substantially raise the maintenance burden of the CI infrastructure. This requirement is subjective, to be evaluated by the infrastructure team, and will take the community importance of the target into account.
• Tier 2 targets should, if at all possible, support cross-compiling. Tier 2 targets should not require using the target as the host for builds, even if the target supports host tools.
• In addition to the legal requirements for all targets (specified in the tier 3 requirements), because a tier 2 target typically involves the Rust project building and supplying various compiled binaries, incorporating the target and redistributing any resulting compiled binaries (e.g. built libraries, host tools if any) must not impose any onerous license requirements on any members of the Rust project, including infrastructure team members and those operating CI systems. This is a subjective requirement, to be evaluated by the approving teams.
  • As an exception to this, if the target's primary purpose is to build components for a Free and Open Source Software (FOSS) project licensed under "copyleft" terms (terms which require licensing other code under compatible FOSS terms), such as kernel modules or plugins, then the standard libraries for the target may potentially be subject to copyleft terms, as long as such terms are satisfied by Rust's existing practices of providing full corresponding source code. Note that anything added to the Rust repository itself must still use Rust's standard license terms.
• Tier 2 targets must not impose burden on the authors of pull requests, or other developers in the community, to ensure that tests pass for the target. In particular, do not post comments (automated or manual) on a PR that derail or suggest a block on the PR based on tests failing for the target. Do not send automated messages or notifications (via any medium, including via @) to a PR author or others involved with a PR regarding the PR breaking tests on a tier 2 target, unless they have opted into such messages.
  • Backlinks such as those generated by the issue/PR tracker when linking to an issue or PR are not considered a violation of this policy, within reason. However, such messages (even on a separate repository) must not generate notifications to anyone involved with a PR who has not requested such notifications.
• The target maintainers should regularly run the testsuite for the target, and should fix any test failures in a reasonably timely fashion.
• All requirements for tier 3 apply.

A tier 2 target may be demoted or removed if it no longer meets these requirements. Any proposal for demotion or removal will be CCed to the target maintainers, and will be communicated widely to the Rust community before being dropped from a stable release. (The amount of time between such communication and the next stable release may depend on the nature and severity of the failed requirement, the timing of its discovery, whether the target has been part of a stable release yet, and whether the demotion or removal can be a planned and scheduled action.)

In some circumstances, especially if the target maintainers do not respond in a timely fashion, Rust teams may land pull requests that temporarily disable some targets in the nightly compiler, in order to implement a feature not yet supported by those targets. (As an example, this happened when introducing the 128-bit types u128 and i128.) Such a pull request will include notification and coordination with the maintainers of such targets, and will ideally happen towards the beginning of a new development cycle to give maintainers time to update their targets. The maintainers of such targets will then be expected to implement the corresponding target-specific support in order to re-enable the target. If the maintainers of such targets cannot provide such support in time for the next stable release, this may result in demoting or removing the targets.

Tier 2 with host tools

Some tier 2 targets may additionally have binaries built to run on them as a host (such as rustc and cargo). This allows the target to be used as a development platform, not just a compilation target.

A proposed new tier 2 target with host tools must be reviewed and approved by the compiler team based on these requirements. Such review and approval may occur via a Major Change Proposal (MCP).

In addition, the infrastructure team must approve the integration of the target's host tools into Continuous Integration (CI), and the CI-related requirements for host tools. This review and approval may take place in a PR adding the target's host tools to CI, or simply by an infrastructure team member reporting the outcome of a team discussion.

• Depending on the target, its capabilities, its performance, and the likelihood of use for any given tool, the host tools provided for a tier 2 target may include only rustc and cargo, or may include additional tools such as clippy and rustfmt.
• Approval of host tools will take into account the additional time required to build the host tools, and the substantial additional storage required for the host tools.
• The host tools must have direct value to people other than the target's maintainers. (It may still be a niche target, but the host tools must not be exclusively useful for an inherently closed group.) This requirement will be evaluated independently from the corresponding tier 2 requirement.
  • The requirement to provide "direct value" means that it does not suffice to argue that having host tools will help the target's maintainers more easily provide the target to others. The tools themselves must provide value to others.
• There must be a reasonable expectation that the host tools will be used, for purposes other than to prove that they can be used.
• The host tools must build and run reliably in CI (for all components that Rust's CI considers mandatory), though they may or may not pass tests.
• Building host tools for the target must not take substantially longer than building host tools for other targets, and should not substantially raise the maintenance burden of the CI infrastructure.
• The host tools must provide a substantively similar experience as on other targets, subject to reasonable target limitations.
  • Adding a substantively different interface to an existing tool, or a target-specific interface to the functionality of an existing tool, requires design and implementation approval (e.g. RFC/MCP) from the appropriate approving teams for that tool.
    • Such an interface should have a design that could potentially work for other targets with similar properties.
    • This should happen separately from the review and approval of the target, to simplify the target review and approval processes, and to simplify the review and approval processes for the proposed new interface.
  • By way of example, a target that runs within a sandbox may need to modify the handling of files, tool invocation, and similar to meet the expectations and conventions of the sandbox, but must not introduce a separate "sandboxed compilation" interface separate from the CLI interface without going through the normal approval process for such an interface. Such an interface should take into account potential other targets with similar sandboxes.
• If the host tools for the platform would normally be expected to be signed or equivalent (e.g. if running unsigned binaries or similar involves a "developer mode" or an additional prompt), it must be possible for the Rust project's automated builds to apply the appropriate signature process, without any manual intervention by either Rust developers, target maintainers, or a third party. This process must meet the approval of the infrastructure team.
  • This process may require one-time or semi-regular manual steps by the infrastructure team, such as registration or renewal of a signing key. Any such manual process must meet the approval of the infrastructure team.
  • This process may require the execution of a legal agreement with the signature provider. Such a legal agreement may be revocable, and may potentially require a nominal fee, but must not be otherwise onerous. Any such legal agreement must meet the approval of the infrastructure team. (The infrastructure team is not expected or required to sign binding legal agreements on behalf of the Rust project; this review and approval exists to ensure no terms are onerous or cause problems for infrastructure, especially if such terms may impose requirements or obligations on people who have access to target-specific infrastructure.)
  • Changes to this process, or to any legal agreements involved, may cause a target to stop meeting this requirement.
  • This process involved must be available under substantially similar non-onerous terms to the general public. Making it available exclusively to the Rust project does not suffice.
  • This requirement exists to ensure that Rust builds, including nightly builds, can meet the necessary requirements to allow users to smoothly run the host tools.
• Providing host tools does not exempt a target from requirements to support cross-compilation if at all possible.
• All requirements for tier 2 apply.

A target may be promoted directly from tier 3 to tier 2 with host tools if it meets all the necessary requirements, but doing so may introduce substantial additional complexity. If in doubt, the target should qualify for tier 2 without host tools first.

Tier 1 target policy

At this tier, the Rust project guarantees that a target builds and passes all tests, and will reject patches that fail to build or pass the testsuite on a target. We hold tier 1 targets to our highest standard of requirements.

A proposed new tier 1 target must be reviewed and approved by the compiler team based on these requirements. In addition, the release team must approve the viability and value of supporting the target. For a tier 1 target, this will typically take place via a full RFC proposing the target, to be jointly reviewed and approved by the compiler team and release team.

In addition, the infrastructure team must approve the integration of the target into Continuous Integration (CI), and the tier 1 CI-related requirements. This review and approval may take place in a PR adding the target to CI, by an infrastructure team member reporting the outcome of a team discussion, or by including the infrastructure team in the RFC proposing the target.

• Tier 1 targets must have substantial, widespread interest within the developer community, and must serve the ongoing needs of multiple production users of Rust across multiple organizations or projects. These requirements are subjective, and determined by consensus of the approving teams. A tier 1 target may be demoted or removed if it becomes obsolete or no longer meets this requirement.
• The target maintainer team must include at least 3 developers.
• The target must build and pass tests reliably in CI, for all components that Rust's CI considers mandatory.
  • The target must not disable an excessive number of tests or pieces of tests in the testsuite in order to do so. This is a subjective requirement.
  • If the target does not have host tools support, or if the target has low performance, the infrastructure team may choose to have CI cross-compile the testsuite from another platform, and then run the compiled tests either natively or via accurate emulation. However, the approving teams may take such performance considerations into account when determining the viability of the target or of its host tools.
• The target must provide as much of the Rust standard library as is feasible and appropriate to provide. For instance, if the target can support dynamic memory allocation, it must provide an implementation of alloc and the associated data structures.
• Building the target and running the testsuite for the target must not take substantially longer than other targets, and should not substantially raise the maintenance burden of the CI infrastructure.
  • In particular, if building the target takes a reasonable amount of time, but the target cannot run the testsuite in a timely fashion due to low performance of either native code or accurate emulation, that alone may prevent the target from qualifying as tier 1.
• If running the testsuite requires additional infrastructure (such as physical systems running the target), the target maintainers must arrange to provide such resources to the Rust project, to the satisfaction and approval of the Rust infrastructure team.
  • Such resources may be provided via cloud systems, via emulation, or via physical hardware.
  • If the target requires the use of emulation to meet any of the tier requirements, the approving teams for those requirements must have high confidence in the accuracy of the emulation, such that discrepancies between emulation and native operation that affect test results will constitute a high-priority bug in either the emulation or the implementation of the target.
  • If it is not possible to run the target via emulation, these resources must additionally be sufficient for the Rust infrastructure team to make them available for access by Rust team members, for the purposes of development and testing. (Note that the responsibility for doing target-specific development to keep the target well maintained remains with the target maintainers. This requirement ensures that it is possible for other Rust developers to test the target, but does not obligate other Rust developers to make target-specific fixes.)
  • Resources provided for CI and similar infrastructure must be available for continuous exclusive use by the Rust project. Resources provided for access by Rust team members for development and testing must be available on an exclusive basis when in use, but need not be available on a continuous basis when not in use.
• Tier 1 targets must not have a hard requirement for signed, verified, or otherwise "approved" binaries. Developers must be able to build, run, and test binaries for the target on systems they control, or provide such binaries for others to run. (Doing so may require enabling some appropriate "developer mode" on such systems, but must not require the payment of any additional fee or other consideration, or agreement to any onerous legal agreements.)
  • The Rust project may decide to supply appropriately signed binaries if doing so provides a smoother experience for developers using the target, and a tier 2 target with host tools already requires providing appropriate mechanisms that enable our infrastructure to provide such signed binaries. However, this additional tier 1 requirement ensures that Rust developers can develop and test Rust software for the target (including Rust itself), and that development or testing for the target is not limited.
• All requirements for tier 2 apply.

A tier 1 target may be demoted if it no longer meets these requirements but still meets the requirements for a lower tier. Any proposal for demotion of a tier 1 target requires a full RFC process, with approval by the compiler and release teams. Any such proposal will be communicated widely to the Rust community, both when initially proposed and before being dropped from a stable release. A tier 1 target is highly unlikely to be directly removed without first being demoted to tier 2 or tier 3. (The amount of time between such communication and the next stable release may depend on the nature and severity of the failed requirement, the timing of its discovery, whether the target has been part of a stable release yet, and whether the demotion or removal can be a planned and scheduled action.)

Raising the baseline expectations of a tier 1 target (such as the minimum CPU features or OS version required) requires the approval of the compiler and release teams, and should be widely communicated as well, but does not necessarily require a full RFC.

Tier 1 with host tools

Some tier 1 targets may additionally have binaries built to run on them as a host (such as rustc and cargo). This allows the target to be used as a development platform, not just a compilation target.

A proposed new tier 1 target with host tools must be reviewed and approved by the compiler team based on these requirements. In addition, the release team must approve the viability and value of supporting host tools for the target. For a tier 1 target, this will typically take place via a full RFC proposing the target, to be jointly reviewed and approved by the compiler team and release team.

In addition, the infrastructure team must approve the integration of the target's host tools into Continuous Integration (CI), and the CI-related requirements for host tools. This review and approval may take place in a PR adding the target's host tools to CI, by an infrastructure team member reporting the outcome of a team discussion, or by including the infrastructure team in the RFC proposing the target.

• Tier 1 targets with host tools should typically include all of the additional tools such as clippy and rustfmt, unless there is a target-specific reason why a tool cannot possibly make sense for the target.
  • Unlike with tier 2, for tier 1 we will not exclude specific tools on the sole basis of them being less likely to be used; rather, we'll take that into account when considering whether the target should be at tier 1 with host tools. In general, on any tier 1 target with host tools, people should be able to expect to find and install all the same components that they would for any other tier 1 target with host tools.
• Approval of host tools will take into account the additional time required to build the host tools, and the substantial additional storage required for the host tools.
• Host tools for the target must have substantial, widespread interest within the developer community, and must serve the ongoing needs of multiple production users of Rust across multiple organizations or projects. These requirements are subjective, and determined by consensus of the approving teams. This requirement will be evaluated independently from the corresponding tier 1 requirement; it is possible for a target to have sufficient interest for cross-compilation, but not have sufficient interest for native compilation. The host tools may be dropped if they no longer meet this requirement, even if the target otherwise qualifies as tier 1.
• The host tools must build, run, and pass tests reliably in CI, for all components that Rust's CI considers mandatory.
  • The target must not disable an excessive number of tests or pieces of tests in the testsuite in order to do so. This is a subjective requirement.
• Building the host tools and running the testsuite for the host tools must not take substantially longer than other targets, and should not substantially raise the maintenance burden of the CI infrastructure.
  • In particular, if building the target's host tools takes a reasonable amount of time, but the target cannot run the testsuite in a timely fashion due to low performance of either native code or accurate emulation, that alone may prevent the target from qualifying as tier 1 with host tools.
• Providing host tools does not exempt a target from requirements to support cross-compilation if at all possible.
• All requirements for tier 2 targets with host tools apply.
• All requirements for tier 1 apply.

A target seeking promotion to tier 1 with host tools should typically either be tier 2 with host tools or tier 1 without host tools, to reduce the number of requirements to simultaneously review and approve.

In addition to the general process for demoting a tier 1 target, a tier 1 target with host tools may be demoted (including having its host tools dropped, or being demoted to tier 2 with host tools) if it no longer meets these requirements but still meets the requirements for a lower tier. Any proposal for demotion of a tier 1 target (with or without host tools) requires a full RFC process, with approval by the compiler and release teams. Any such proposal will be communicated widely to the Rust community, both when initially proposed and before being dropped from a stable release.

target-name-here

Tier: 3

One-sentence description of the target (e.g. CPU, OS)

Target maintainers

• Some Person, https://github.com/...

Requirements

Does the target support host tools, or only cross-compilation? Does the target support std, or alloc (either with a default allocator, or if the user supplies an allocator)?

Document the expectations of binaries built for the target. Do they assume specific minimum features beyond the baseline of the CPU/environment/etc? What version of the OS or environment do they expect?

Are there notable #[target_feature(...)] or -C target-feature= values that programs may wish to use?

What calling convention does extern "C" use on the target?

What format do binaries use by default? ELF, PE, something else?

Building the target

If Rust doesn't build the target by default, how can users build it? Can users just add it to the target list in config.toml?

Building Rust programs

Rust does not yet ship pre-compiled artifacts for this target. To compile for this target, you will either need to build Rust with the target enabled (see "Building the target" above), or build your own copy of core by using build-std or similar.

Testing

Does the target support running binaries, or do binaries have varying expectations that prevent having a standard way to run them? If users can run binaries, can they do so in some common emulator, or do they need native hardware? Does the target support running the Rust testsuite?

Cross-compilation toolchains and C code

Does the target support C code? If so, what toolchain target should users use to build compatible C code? (This may match the target triple, or it may be a toolchain for a different target triple, potentially with specific options or caveats.)

arm64ec-pc-windows-msvc

Tier: 2

Arm64EC ("Emulation Compatible") for mixed architecture (AArch64 and x86_64) applications on AArch64 Windows 11. See https://learn.microsoft.com/en-us/windows/arm/arm64ec.

Target maintainers

• @dpaoliello

Requirements

Builds Arm64EC static and dynamic libraries and executables which can be run on AArch64 Windows 11 devices. Arm64EC static libraries can also be linked into Arm64X dynamic libraries and executables.

Only supported backend is LLVM 18 or above:

• 18.1.0 added initial support for Arm64EC.
• 18.1.2 fixed import library generation (required for raw-dylib support).
• 18.1.4 fixed linking issue for some intrinsics implemented in compiler_builtins.

Visual Studio 2022 (or above) with the "ARM64/ARM64EC built tools" component and the Windows 11 SDK are required.

Reusing code from other architectures - x86_64 or AArch64?

Arm64EC uses arm64ec as its target_arch, but it is possible to reuse existing architecture-specific code in most cases. The best mental model for deciding which architecture to reuse is to is to think of Arm64EC as an x86_64 process that happens to use the AArch64 instruction set (with some caveats) and has a completely custom ABI.

To put this in practice:

• Arm64EC interacts with the operating system, other processes and other DLLs as x86_64.
  • For example, in backtrace we use the x86_64 versions of CONTEXT and RtlVirtualUnwind.
  • If you are configuring a search path to find DLLs (e.g., to load plugins or addons into your application), you should use the same path as the x86_64 version of your application, not the AArch64 path (since Arm64EC (i.e., x86_64) processes cannot load native AArch64 DLLs).
• Arm64EC uses AArch64 intrinsics.
  • For example, https://github.com/rust-lang/portable-simd/commit/ca4033f49b1f6019561b8b161b4097b4a07f2e1b and https://github.com/rust-lang/stdarch/commit/166ef7ba22b6a1d908d4b29a36e68ceca324808a.
• Assembly for AArch64 might be reusable for Arm64EC, but there are many caveats. For full details see Microsoft's documentation on the Arm64EC ABI but in brief:
  • Arm64EC uses a subset of AArch64 registers.
  • Arm64EC uses a different name mangling scheme than AArch64.
  • Arm64EC requires entry and exit thunks be generated for some functions.
  • Indirect calls must be done via a call checker.
  • Control Flow Guard and stack checks use different functions than AArch64.

Building the target

You can build Rust with support for the targets by adding it to the target list in config.toml:

[build]
target = ["arm64ec-pc-windows-msvc"]

Building Rust programs

These targets are distributed through rustup, and otherwise require no special configuration.

Testing

Tests can be run on AArch64 Windows 11 devices.

Cross-compilation toolchains and C code

C code can be built using the Arm64-targeting MSVC or Clang toolchain.

To compile:

cl /arm64EC /c ...

To link:

link /MACHINE:ARM64EC ...

Further reading: https://learn.microsoft.com/en-us/windows/arm/arm64ec-build

*-apple-darwin

Apple macOS targets.

Tier: 1

• x86_64-apple-darwin: macOS on 64-bit x86.
• aarch64-apple-darwin: macOS on ARM64 (M1-family or later Apple Silicon CPUs).

Target maintainers

• @thomcc
• @madsmtm

Requirements

OS version

The minimum supported version is macOS 10.12 Sierra on x86, and macOS 11.0 Big Sur on ARM64.

This version can be raised per-binary by changing the deployment target, which might yield more performance optimizations. rustc respects the common environment variables used by Xcode to do so, in this case MACOSX_DEPLOYMENT_TARGET.

The current default deployment target for rustc can be retrieved with rustc --print=deployment-target.

Host tooling

The minimum supported OS versions for the host tooling (rustc, cargo, etc.) are currently the same as for applications, namely 10.12 on x86 and 11.0 on ARM64. The minimum supported Xcode version is 9.2.

Building from source likely requires that you can build LLVM from source too, which currently requires Xcode 10.0 and macOS 10.13 (for LLVM 19).

Binary format

The default binary format is Mach-O, the executable format used on Apple's platforms.

Building

These targets are distributed through rustup, and otherwise require no special configuration.

Testing

There are no special requirements for testing and running this target.

x86 binaries can be run on Apple Silicon by using Rosetta.

Cross-compilation toolchains and C code

Cross-compilation of these targets are supported using Clang, but may require Xcode or the macOS SDK (MacOSX.sdk) to be available to compile C code and to link.

The Clang target is suffixed with -macosx. Clang's -darwin target refers to Darwin platforms in general (macOS/iOS/tvOS/watchOS/visionOS), and requires the -mmacosx-version-min=..., -miphoneos-version-min=... or similar flags to disambiguate.

The path to the SDK can be passed to rustc using the common SDKROOT environment variable.

i686-apple-darwin

Apple macOS on 32-bit x86.

Target maintainers

• @thomcc
• @madsmtm

Requirements

See the docs on *-apple-darwin for general macOS requirements.

Building the target

You'll need the macOS 10.13 SDK shipped with Xcode 9. The location of the SDK can be passed to rustc using the common SDKROOT environment variable.

Once you have that, you can build Rust with support for the target by adding it to the target list in config.toml:

[build]
target = ["i686-apple-darwin"]

Using the unstable -Zbuild-std with a nightly Cargo may also work.

Building Rust programs

Rust no longer ships pre-compiled artifacts for this target. To compile for this target, you will either need to build Rust with the target enabled (see "Building the target" above), or build your own copy using build-std or similar.

Testing

Running this target requires an Intel Macbook running macOS 10.14 or earlier, as later versions removed support for running 32-bit binaries.

x86_64h-apple-darwin

Tier: 3

Target for macOS on late-generation x86_64 Apple chips, usable as the x86_64h entry in universal binaries, and equivalent to LLVM's x86_64h-apple-macosx* targets.

Target maintainers

• Thom Chiovoloni thom@shift.click https://github.com/thomcc

Requirements

This target is an x86_64 target that only supports Apple's late-gen (Haswell-compatible) Intel chips. It enables a set of target features available on these chips (AVX2 and similar), and MachO binaries built with this target may be used as the x86_64h entry in universal binaries ("fat" MachO binaries), and will fail to load on machines that do not support this.

It should support the full standard library (std and alloc either with default or user-defined allocators). This target is probably most useful when targeted via cross-compilation (including from x86_64-apple-darwin), but if built manually, the host tools work.

It is similar to x86_64-apple-darwin in nearly all respects.

Building the target

Users on Apple targets can build this by adding it to the target list in config.toml, or with -Zbuild-std.

Building Rust programs

Rust does not yet ship pre-compiled artifacts for this target. To compile for this target, you will either need to build Rust with the target enabled (see "Building the target" above), or build your own copy of core by using build-std or similar.

Testing

Code built with this target can be run on the set of Intel macOS machines that support running x86_64h binaries (relatively recent Intel macs). The Rust test suite seems to work.

Cross-compilation toolchains and C code

Cross-compilation to this target from Apple hosts should generally work without much configuration, so long as XCode and the CommandLineTools are installed. Targeting it from non-Apple hosts is difficult, but no more so than targeting x86_64-apple-darwin.

When compiling C code for this target, either the "x86_64h-apple-macosx*" LLVM targets should be used, or an argument like -arch x86_64h should be passed to the C compiler.

arm64e-apple-darwin

Tier: 3 (with Host Tools)

ARM64e macOS (11.0+, Big Sur+)

Target maintainers

• Artyom Tetyukhin (@arttet)

Requirements

Target for macOS on late-generation M series Apple chips.

See the docs on *-apple-darwin for general macOS requirements.

Building the target

You can build Rust with support for the targets by adding it to the target list in config.toml:

[build]
target = ["arm64e-apple-darwin"]

Building Rust programs

Rust does not yet ship pre-compiled artifacts for this target. To compile for this target, you will need to build Rust with the target enabled (see Building the target above).

Testing

The target does support running binaries on macOS platforms with arm64e architecture.

Cross-compilation toolchains and C code

The targets do support C code. To build compatible C code, you have to use XCode with the same compiler and flags.

*-apple-ios

Apple iOS / iPadOS targets.

Tier: 2 (without Host Tools)

• aarch64-apple-ios: Apple iOS on ARM64.
• aarch64-apple-ios-sim: Apple iOS Simulator on ARM64.
• x86_64-apple-ios: Apple iOS Simulator on 64-bit x86.

Tier: 3

• armv7s-apple-ios: Apple iOS on Armv7-A.
• i386-apple-ios: Apple iOS Simulator on 32-bit x86.

Target maintainers

• @badboy
• @deg4uss3r
• @madsmtm

Requirements

These targets are cross-compiled, and require the corresponding iOS SDK (iPhoneOS.sdk or iPhoneSimulator.sdk), as provided by Xcode. To build the ARM64 targets, Xcode 12 or higher is required.

The path to the SDK can be passed to rustc using the common SDKROOT environment variable.

OS version

The minimum supported version is iOS 10.0.

This can be raised per-binary by changing the deployment target. rustc respects the common environment variables used by Xcode to do so, in this case IPHONEOS_DEPLOYMENT_TARGET.

Building the target

The tier 2 targets are distributed through rustup, and can be installed using one of:

$ rustup target add aarch64-apple-ios
$ rustup target add aarch64-apple-ios-sim
$ rustup target add x86_64-apple-ios

The tier 3 targets can be built by enabling them for a rustc build in config.toml, by adding, for example:

[build]
target = ["armv7s-apple-ios", "i386-apple-ios"]

Using the unstable -Zbuild-std with a nightly Cargo may also work.

Building Rust programs

Rust programs can be built for these targets by specifying --target, if rustc has been built with support for them. For example:

$ rustc --target aarch64-apple-ios your-code.rs

Testing

There is no support for running the Rust or standard library testsuite at the moment. Testing has mostly been done manually with builds of static libraries embedded into applications called from Xcode or a simulator.

It hopefully will be possible to improve this in the future.

*-apple-ios-macabi

Apple Mac Catalyst targets.

Tier: 2 (without Host Tools)

• aarch64-apple-ios-macabi: Mac Catalyst on ARM64.
• x86_64-apple-ios-macabi: Mac Catalyst on 64-bit x86.

Target maintainers

• @badboy
• @BlackHoleFox
• @madsmtm

Requirements

These targets are cross-compiled, and require the corresponding macOS SDK (MacOSX.sdk) which contain ./System/iOSSupport headers to allow linking to iOS-specific headers, as provided by Xcode 11 or higher.

The path to the SDK can be passed to rustc using the common SDKROOT environment variable.

OS version

The minimum supported version is iOS 13.1 on x86 and 14.0 on Aarch64.

This can be raised per-binary by changing the deployment target. rustc respects the common environment variables used by Xcode to do so, in this case IPHONEOS_DEPLOYMENT_TARGET.

Building the target

The targets are distributed through rustup, and can be installed using one of:

$ rustup target add aarch64-apple-ios-macabi
$ rustup target add x86_64-apple-ios-macabi

Sanitizers

Due to CMake having poor support for Mac Catalyst, sanitizer runtimes are not currently available, see #129069.

Building Rust programs

Rust programs can be built for these targets by specifying --target, if rustc has been built with support for them. For example:

$ rustc --target aarch64-apple-ios-macabi your-code.rs

Testing

Mac Catalyst binaries can be run directly on macOS 10.15 Catalina or newer.

x86 binaries can be run on Apple Silicon by using Rosetta.

Note that using certain UIKit functionality requires the binary to be bundled.

arm64e-apple-ios

Tier: 3

ARM64e iOS (14.0+)

Target maintainers

• Artyom Tetyukhin (@arttet)

Requirements

See the docs on *-apple-ios for general iOS requirements.

Building the target

You can build Rust with support for the targets by adding it to the target list in config.toml:

[build]
target = ["arm64e-apple-ios"]

Building Rust programs

Rust does not yet ship pre-compiled artifacts for this target. To compile for this target, you will need to build Rust with the target enabled (see Building the target above).

Testing

The target does support running binaries on iOS platforms with arm64e architecture.

Cross-compilation toolchains and C code

The targets do support C code. To build compatible C code, you have to use XCode with the same compiler and flags.

*-apple-tvos

Apple tvOS targets.

Tier: 3

• aarch64-apple-tvos: Apple tvOS on ARM64.
• aarch64-apple-tvos-sim: Apple tvOS Simulator on ARM64.
• x86_64-apple-tvos: Apple tvOS Simulator on x86_64.

Target maintainers

• @thomcc
• @madsmtm

Requirements

These targets are cross-compiled, and require the corresponding tvOS SDK (AppleTVOS.sdk or AppleTVSimulator.sdk), as provided by Xcode. To build the ARM64 targets, Xcode 12 or higher is required.

The path to the SDK can be passed to rustc using the common SDKROOT environment variable.

OS version

The minimum supported version is tvOS 10.0, although the actual minimum version you can target may be newer than this, for example due to the versions of Xcode and your SDKs.

The version can be raised per-binary by changing the deployment target. rustc respects the common environment variables used by Xcode to do so, in this case TVOS_DEPLOYMENT_TARGET.

Incompletely supported library functionality

The targets support most of the standard library including the allocator to the best of my knowledge, however they are very new, not yet well-tested, and it is possible that there are various bugs.

The following APIs are currently known to have missing or incomplete support:

• std::process::Command's API will return an error if it is configured in a manner which cannot be performed using posix_spawn -- this is because the more flexible fork/exec-based approach is prohibited on these platforms in favor of posix_spawn{,p} (which still probably will get you rejected from app stores, so is likely sideloading-only). A concrete set of cases where this will occur is difficult to enumerate (and would quickly become stale), but in some cases it may be worked around by tweaking the manner in which Command is invoked.

Building the target

The targets can be built by enabling them for a rustc build in config.toml, by adding, for example:

[build]
build-stage = 1
target = ["aarch64-apple-tvos", "aarch64-apple-tvos-sim"]

Using the unstable -Zbuild-std with a nightly Cargo may also work.

Building Rust programs

Rust programs can be built for these targets by specifying --target, if rustc has been built with support for them. For example:

$ rustc --target aarch64-apple-tvos your-code.rs

Testing

There is no support for running the Rust or standard library testsuite at the moment. Testing has mostly been done manually with builds of static libraries embedded into applications called from Xcode or a simulator.

It hopefully will be possible to improve this in the future.

arm64e-apple-tvos

Tier: 3

ARM64e tvOS (10.0+)

Target maintainers

• Artyom Tetyukhin (@arttet)

Requirements

This target is cross-compiled and supports std. To build this target Xcode 12 or higher on macOS is required.

Building the target

You can build Rust with support for the targets by adding it to the target list in config.toml:

[build]
target = ["arm64e-apple-tvos"]

Building Rust programs

Rust does not yet ship pre-compiled artifacts for this target. To compile for this target, you will need to build Rust with the target enabled (see Building the target above).

Testing

The target does support running binaries on tvOS platforms with arm64e architecture.

Cross-compilation toolchains and C code

The targets do support C code. To build compatible C code, you have to use XCode with the same compiler and flags.

*-apple-watchos

Apple watchOS targets.

Tier: 3

• aarch64-apple-watchos: Apple WatchOS on ARM64.
• aarch64-apple-watchos-sim: Apple WatchOS Simulator on ARM64.
• x86_64-apple-watchos-sim: Apple WatchOS Simulator on 64-bit x86.
• arm64_32-apple-watchos: Apple WatchOS on Arm 64_32.
• armv7k-apple-watchos: Apple WatchOS on Armv7k.

Target maintainers

• @deg4uss3r
• @vladimir-ea
• @leohowell
• @madsmtm

Requirements

These targets are cross-compiled, and require the corresponding watchOS SDK (WatchOS.sdk or WatchSimulator.sdk), as provided by Xcode. To build the ARM64 targets, Xcode 12 or higher is required.

The path to the SDK can be passed to rustc using the common SDKROOT environment variable.

OS version

The minimum supported version is watchOS 5.0.

This can be raised per-binary by changing the deployment target. rustc respects the common environment variables used by Xcode to do so, in this case WATCHOS_DEPLOYMENT_TARGET.

Building the target

The targets can be built by enabling them for a rustc build in config.toml, by adding, for example:

[build]
build-stage = 1
target = ["aarch64-apple-watchos", "aarch64-apple-watchos-sim"]

Using the unstable -Zbuild-std with a nightly Cargo may also work.

Building Rust programs

Rust programs can be built for these targets by specifying --target, if rustc has been built with support for them. For example:

$ rustc --target aarch64-apple-watchos-sim your-code.rs

Testing

There is no support for running the Rust or standard library testsuite at the moment. Testing has mostly been done manually with builds of static libraries embedded into applications called from Xcode or a simulator.

It hopefully will be possible to improve this in the future.

*-apple-visionos

Apple visionOS / xrOS targets.

Tier: 3

• aarch64-apple-visionos: Apple visionOS on arm64.
• aarch64-apple-visionos-sim: Apple visionOS Simulator on arm64.

Target maintainers

• @agg23
• @madsmtm

Requirements

These targets are cross-compiled, and require the corresponding visionOS SDK (XROS.sdk or XRSimulator.sdk), as provided by Xcode 15 or newer.

The path to the SDK can be passed to rustc using the common SDKROOT environment variable.

OS version

The minimum supported version is visionOS 1.0.

This can be raised per-binary by changing the deployment target. rustc respects the common environment variables used by Xcode to do so, in this case XROS_DEPLOYMENT_TARGET.

Building the target

The targets can be built by enabling them for a rustc build in config.toml, by adding, for example:

[build]
target = ["aarch64-apple-visionos", "aarch64-apple-visionos-sim"]

Using the unstable -Zbuild-std with a nightly Cargo may also work.

Note: Currently, a newer version of libc and cc may be required, this will be fixed in #124560.

Building Rust programs

Rust programs can be built for these targets by specifying --target, if rustc has been built with support for them. For example:

$ rustc --target aarch64-apple-visionos-sim your-code.rs

Testing

There is no support for running the Rust or standard library testsuite at the moment. Testing has mostly been done manually with builds of static libraries embedded into applications called from Xcode or a simulator.

It hopefully will be possible to improve this in the future.

Cross-compilation toolchains and C code

The Clang target is suffixed with -xros for historical reasons.

LLVM 18 or newer is required to build this target.

aarch64-nintendo-switch-freestanding

Tier: 3

Nintendo Switch with pure-Rust toolchain.

Designated Developers

• @leo60228
• @jam1garner

Requirements

This target is cross-compiled. It has no special requirements for the host.

Building

The target can be built by enabling it for a rustc build:

[build]
build-stage = 1
target = ["aarch64-nintendo-switch-freestanding"]

Cross-compilation

This target can be cross-compiled from any host.

Testing

Currently there is no support to run the rustc test suite for this target.

Building Rust programs

If rustc has support for that target and the library artifacts are available, then Rust programs can be built for that target:

rustc --target aarch64-nintendo-switch-freestanding your-code.rs

To generate binaries in the NRO format that can be easily run on-device, you can use cargo-nx:

cargo nx --triple=aarch64-nintendo-switch-freestanding

amdgcn-amd-amdhsa

Tier: 3

AMD GPU target for compute/HSA (Heterogeneous System Architecture).

Target maintainers

• @Flakebi

Requirements

AMD GPUs can be targeted via cross-compilation. Supported GPUs depend on the LLVM version that is used by Rust. In general, most GPUs starting from gfx7 (Sea Islands/CI) are supported as compilation targets, though older GPUs are not supported by the latest host runtime. Details about supported GPUs can be found in LLVM’s documentation and ROCm documentation.

Binaries can be loaded by HIP or by the HSA runtime implemented in ROCR-Runtime. The format of binaries is a linked ELF.

Binaries must be built with no-std. They can use core and alloc (alloc only if an allocator is supplied). At least one function needs to use the "gpu-kernel" calling convention and should be marked with no_mangle for simplicity. Functions using the "gpu-kernel" calling convention are kernel entrypoints and can be used from the host runtime.

Building the target

The target is included in rustc.

Building Rust programs

The amdgpu target supports many hardware generations, which need different binaries. The generations are exposed as different target-cpus in the backend. As there are many, Rust does not ship pre-compiled libraries for this target. Therefore, you have to build your own copy of core by using cargo -Zbuild-std=core or similar.

To build a binary, create a no-std library:

// src/lib.rs
#![feature(abi_gpu_kernel)]
#![no_std]

#[panic_handler]
fn panic(_: &core::panic::PanicInfo) -> ! {
    loop {}
}

#[no_mangle]
pub extern "gpu-kernel" fn kernel(/* Arguments */) {
    // Code
}

Build the library as cdylib:

# Cargo.toml
[lib]
crate-type = ["cdylib"]

[profile.dev]
lto = true # LTO must be explicitly enabled for now
[profile.release]
lto = true

The target-cpu must be from the list supported by LLVM (or printed with rustc --target amdgcn-amd-amdhsa --print target-cpus). The GPU version on the current system can be found e.g. with rocminfo.

Example .cargo/config.toml file to set the target and GPU generation:

# .cargo/config.toml
[build]
target = "amdgcn-amd-amdhsa"
rustflags = ["-Ctarget-cpu=gfx1100"]

[unstable]
build-std = ["core"] # Optional: "alloc"

Running Rust programs

To run a binary on an AMD GPU, a host runtime is needed. On Linux and Windows, HIP can be used to load and run binaries. Example code on how to load a compiled binary and run it is available in ROCm examples.

On Linux, binaries can also run through the HSA runtime as implemented in ROCR-Runtime.

Additional information

More information can be found on the LLVM page for amdgpu.

armeb-unknown-linux-gnueabi

Tier: 3

Target for cross-compiling Linux user-mode applications targeting the Arm BE8 architecture.

Overview

BE8 architecture retains the same little-endian ordered code-stream used by conventional little endian Arm systems, however the data accesses are in big-endian. BE8 is used primarily in high-performance networking applications where the ability to read packets in their native "Network Byte Order" is important (many network protocols transmit data in big-endian byte order for their wire formats).

History

BE8 architecture is the default big-endian architecture for Arm since Armv6. It's predecessor, used for Armv4 and Armv5 devices was BE32. On Armv6 architecture, endianness can be configured via system registers. However, BE32 was withdrawn for Armv7 onwards.

Target Maintainers

• @WorksButNotTested

Requirements

The target is cross-compiled. This target supports std in the normal way (indeed only nominal changes are required from the standard Arm configuration).

Target definition

The target definition can be seen here. In particular, it should be noted that the features specify that this target is built for the Armv8 core. Though this can likely be modified as required.

Building the target

Because it is Tier 3, rust does not yet ship pre-compiled artifacts for this target.

Therefore, you can build Rust with support for the target by adding it to the target list in config.toml, a sample configuration is shown below. It is expected that the user already have a working GNU compiler toolchain and update the paths accordingly.

[llvm]
download-ci-llvm = false
optimize = true
ninja = true
targets = "ARM;X86"
clang = false

[build]
target = ["x86_64-unknown-linux-gnu", "armeb-unknown-linux-gnueabi"]
docs = false
docs-minification = false
compiler-docs = false
[install]
prefix = "/home/user/x-tools/rust/"

[rust]
debug-logging=true
backtrace = true
incremental = true

[target.x86_64-unknown-linux-gnu]

[dist]

[target.armeb-unknown-linux-gnueabi]
cc = "/home/user/x-tools/armeb-unknown-linux-gnueabi/bin/armeb-unknown-linux-gnueabi-gcc"
cxx = "/home/user/x-tools/armeb-unknown-linux-gnueabi/bin/armeb-unknown-linux-gnueabi-g++"
ar = "/home/user/x-tools/armeb-unknown-linux-gnueabi/bin/armeb-unknown-linux-gnueabi-ar"
ranlib = "/home/user/x-tools/armeb-unknown-linux-gnueabi/bin/armeb-unknown-linux-gnueabi-ranlib"
linker = "/home/user/x-tools/armeb-unknown-linux-gnueabi/bin/armeb-unknown-linux-gnueabi-gcc"
llvm-config = "/home/user/x-tools/clang/bin/llvm-config"
llvm-filecheck = "/home/user/x-tools/clang/bin/FileCheck"

Building Rust programs

The following .cargo/config is needed inside any project directory to build for the BE8 target:

[build]
target = "armeb-unknown-linux-gnueabi"

[target.armeb-unknown-linux-gnueabi]
linker = "armeb-unknown-linux-gnueabi-gcc"

Note that it is expected that the user has a suitable linker from the GNU toolchain.

{arm,thumb}*-none-eabi(hf)?

Common Target Details

This documentation covers details that apply to a range of bare-metal targets for 32-bit Arm CPUs. The arm-none-eabi flavor of the GNU compiler toolchain is often used to assist compilation to these targets.

Details that apply only to only a specific target in this group are covered in their own document.

Tier 2 Target List

• Arm A-Profile Architectures
  • armv7a-none-eabi
• Arm R-Profile Architectures
  • armv7r-none-eabi and armv7r-none-eabihf
  • armebv7r-none-eabi and armebv7r-none-eabihf
• Arm M-Profile Architectures
  • thumbv6m-none-eabi
  • thumbv7m-none-eabi
  • thumbv7em-none-eabi and thumbv7em-none-eabihf
  • thumbv8m.base-none-eabi
  • thumbv8m.main-none-eabi and thumbv8m.main-none-eabihf
• Legacy Arm Architectures
  • None

Tier 3 Target List

• Arm A-Profile Architectures
  • armv7a-none-eabihf
• Arm R-Profile Architectures
  • armv8r-none-eabihf
• Arm M-Profile Architectures
  • None
• Legacy Arm Architectures
  • armv4t-none-eabi and thumbv4t-none-eabi
  • armv5te-none-eabi and thumbv5te-none-eabi

Instruction Sets

There are two 32-bit instruction set architectures (ISAs) defined by Arm:

• The A32 ISA, with fixed-width 32-bit instructions. Previously known as the Arm ISA, this originated with the original ARM1 of 1985 and has been updated by various revisions to the architecture specifications ever since.
• The T32 ISA, with a mix of 16-bit and 32-bit width instructions. Note that this term includes both the original 16-bit width Thumb ISA introduced with the Armv4T architecture in 1994, and the later 16/32-bit sized Thumb-2 ISA introduced with the Armv6T2 architecture in 2003. Again, these ISAs have been revised by subsequent revisions to the relevant Arm architecture specifications.

There is also a 64-bit ISA with fixed-width 32-bit instructions called the A64 ISA, but targets which implement that instruction set generally start with aarch64* and are discussed elsewhere.

Rust targets starting with arm* generate Arm (A32) code by default, whilst targets named thumb* generate Thumb (T32) code by default. Most Arm chips support both Thumb mode and Arm mode, with the notable exception that M-profile processors (thumbv*m*-none-eabi* targets) only support Thumb-mode.

Rust targets ending with eabi use the so-called soft-float ABI: functions which take f32 or f64 as arguments will have those values packed into integer registers. This means that an FPU is not required from an ABI perspective, but within a function floating-point instructions may still be used if the code is compiled with a target-cpu or target-feature option that enables FPU support.

Rust targets ending in eabihf use the so-called hard-float ABI: functions which take f32 or f64 as arguments will have them passed via FPU registers. These targets therefore require the availability of an FPU and will assume some baseline level of floating-point support is available (which can vary depending on the target). More advanced floating-point instructions may be generated if the code is compiled with a target-cpu or target-feature option that enables such additional FPU support. For example, if a given hard-float target has baseline single-precision (f32) support in hardware, there may be target-cpu or target-feature options that tell LLVM to assume your processor in fact also has double-precision (f64) support.

You may of course use the f32 and f64 types in your code, regardless of the ABI being used, or the level of support your processor has for performing such operations in hardware. Any floating-point operations that LLVM assumes your processor cannot support will be lowered to library calls (like __aeabi_dadd) which perform the floating-point operation in software using integer instructions.

Target CPU and Target Feature options

It is possible to tell Rust (or LLVM) that you have a specific model of Arm processor, using the -C target-cpu option. You can also control whether Rust (or LLVM) will include instructions that target optional hardware features, e.g. hardware floating-point, or Advanced SIMD operations, using -C target-feature.

It is important to note that selecting a target-cpu will typically enable all the optional features available from Arm on that model of CPU and your particular implementation of that CPU may not have those features available. In that case, you can use -C target-feature=-option to turn off the specific CPU features you do not have available, leaving you with the optimized instruction scheduling and support for the features you do have. More details are available in the detailed target-specific documentation.

If you wish to use the target-cpu and target-feature options, you can add them to your .cargo/config.toml file alongside any other flags your project uses (likely linker related ones):

rustflags = [
  # Usual Arm bare-metal linker setup
  "-Clink-arg=-Tlink.x",
  "-Clink-arg=--nmagic",
  # tell Rust we have a Cortex-M55
  "-Ctarget-cpu=cortex-m55",
  # tell Rust our Cortex-M55 doesn't have Floating-Point M-Profile Vector
  # Extensions (but it does have everything else a Cortex-M55 could have).
  "-Ctarget-feature=-mve.fp"
]

[build]
target = "thumbv8m.main-none-eabihf"

Requirements

These targets are cross-compiled and use static linking.

By default, the lld linker included with Rust will be used; however, you may want to use the GNU linker instead. This can be obtained for Windows/Mac/Linux from the Arm Developer Website, or possibly from your OS's package manager. To use it, add the following to your .cargo/config.toml:

[target.<your-target>]
linker = "arm-none-eabi-ld"

The GNU linker can also be used by specifying arm-none-eabi-gcc as the linker. This is needed when using GCC's link time optimization.

These targets don't provide a linker script, so you'll need to bring your own according to the specific device you are using. Pass -Clink-arg=-Tyour_script.ld as a rustc argument to make the linker use your_script.ld during linking.

For the arm* targets, Thumb-mode code generation can be enabled by using -C target-feature=+thumb-mode. Using the unstable #![feature(arm_target_feature)], the attribute #[target_feature(enable = "thumb-mode")] can be applied to individual unsafe functions to cause those functions to be compiled to Thumb-mode code.

Building Rust Programs

For the Tier 3 targets in this family, rust does not ship pre-compiled artifacts.

Just use the build-std nightly cargo feature to build the core library. You can pass this as a command line argument to cargo, or your .cargo/config.toml file might include the following lines:

[unstable]
build-std = ["core"]

Most of core should work as expected, with the following notes:

• Floating-point operations are emulated in software unless LLVM is told to enable FPU support (either by using an eabihf target, specifying a target-cpu with FPU support, or using a target-feature to support for a specific kind of FPU)
• Integer division is also emulated in software on some targets, depending on the target, target-cpu and target-features.
• Older Arm architectures (e.g. Armv4, Armv5TE and Armv6-M) are limited to basic load and store operations, and not more advanced operations like fetch_add or compare_exchange.

alloc is also supported, as long as you provide your own global allocator.

Rust programs are output as ELF files.

Testing

This is a cross-compiled target that you will need to emulate during testing.

The exact emulator that you'll need depends on the specific device you want to run your code on.

Cross-compilation toolchains and C code

The target supports C code compiled with the arm-none-eabi target triple and a suitable -march or -mcpu flag.

gcc or clang can be used, but note that gcc uses -fshort-enums by default for arm-none* targets, while clang does not. rustc matches the gcc behavior, i.e., the size of a #[repr(C)] enum in Rust can be as little as 1 byte, rather than 4, as they are on arm-linux targets.

armv4t-none-eabi / thumbv4t-none-eabi

Tier 3

These two targets are part of the arm-none-eabi target group, and all the information there applies.

Both of these targets can be used on the Game Boy Advance (GBA), among other things. On the GBA, one should usually use the thumb target to get the best overall performance.

Target Maintainers

• @Lokathor
• @corwinkuiper

Testing

This is a cross-compiled target that you will need to emulate during testing.

Because this is a device-agnostic target, and the exact emulator that you'll need depends on the specific device you want to run your code on.

• When building for the GBA, mgba-test-runner can be used to make a normal set of rust tests be run within the mgba emulator.

armv5te-none-eabi

Tier: 3

Bare-metal target for any cpu in the Armv5TE architecture family, supporting ARM/Thumb code interworking (aka A32/T32), with A32 code as the default code generation.

The thumbv5te-none-eabi target is the same as this one, but the instruction set defaults to T32.

See arm-none-eabi for information applicable to all arm-none-eabi targets.

Target Maintainers

• @QuinnPainter

Testing

This is a cross-compiled target that you will need to emulate during testing.

Because this is a device-agnostic target, and the exact emulator that you'll need depends on the specific device you want to run your code on.

For example, when programming for the DS, you can use one of the several available DS emulators, such as melonDS.

arm(eb)?v7r-none-eabi(hf)?

Tier: 2

Bare-metal target for CPUs in the Armv7-R architecture family, supporting dual ARM/Thumb mode, with ARM mode as the default.

Processors in this family include the Arm Cortex-R4, 5, 7, and 8.

The eb versions of this target generate code for big-endian processors.

See arm-none-eabi for information applicable to all arm-none-eabi targets.

Target maintainers

• Chris Copeland, chris@chrisnc.net

Requirements

When using the big-endian version of this target, note that some variants of the Cortex-R have both big-endian instructions and data. This configuration is known as BE-32, while data-only big-endianness is known as BE-8. To build programs for BE-32 processors, the GNU linker must be used with the -mbe32 option. See ARM Cortex-R Series Programmer's Guide: Endianness for more details about different endian modes.

When using the hardfloat targets, the minimum floating-point features assumed are those of the vfpv3-d16, which includes single- and double-precision, with 16 double-precision registers. This floating-point unit appears in Cortex-R4F and Cortex-R5F processors. See VFP in the Cortex-R processors for more details on the possible FPU variants.

If your processor supports a different set of floating-point features than the default expectations of vfpv3-d16, then these should also be enabled or disabled as needed with -C target-feature=(+/-).

Cross-compilation toolchains and C code

This target supports C code compiled with the arm-none-eabi target triple and -march=armv7-r or a suitable -mcpu flag.

armv8r-none-eabihf

Tier: 3

Bare-metal target for CPUs in the Armv8-R architecture family, supporting dual ARM/Thumb mode, with ARM mode as the default.

Processors in this family include the Arm Cortex-R52 and Cortex-R52+.

See arm-none-eabi for information applicable to all arm-none-eabi targets.

Target maintainers

• Chris Copeland, chris@chrisnc.net

Requirements

The Cortex-R52 family always includes a floating-point unit, so there is no non-hf version of this target. The floating-point features assumed by this target are those of the single-precision-only config of the Cortex-R52, which has 16 double-precision registers, accessible as 32 single-precision registers. The other variant of Cortex-R52 includes double-precision, 32 double-precision registers, and Advanced SIMD (Neon).

The manual refers to this as the "Full Advanced SIMD config". To compile code for this variant, use: -C target-feature=+fp64,+d32,+neon. See the Advanced SIMD and floating-point support section of the Cortex-R52 Processor Technical Reference Manual for more details.

Cross-compilation toolchains and C code

This target supports C code compiled with the arm-none-eabi target triple and -march=armv8-r or a suitable -mcpu flag.

thumbv6m-none-eabi

Tier: 2

Bare-metal target for CPUs in the Armv6-M architecture family, supporting a subset of the T32 ISA.

Processors in this family include the:

• Arm Cortex-M0
• Arm Cortex-M0+
• Arm Cortex-M1

See arm-none-eabi for information applicable to all arm-none-eabi targets.

This target uses the soft-float ABI: functions which take f32 or f64 as arguments will have those values packed into integer registers. This is the only option because there is no FPU support in Armv6-M.

Target maintainers

• Rust Embedded Devices Working Group Cortex-M Team, cortex-m@teams.rust-embedded.org

Target CPU and Target Feature options

See the bare-metal Arm docs for details on how to use these flags.

Table of supported CPUs

Arm Cortex-M0

The target CPU option is cortex-m0.

There are no relevant feature flags, and the FPU is not available.

Arm Cortex-M0+

The target CPU option is cortex-m0plus.

There are no relevant feature flags, and the FPU is not available.

Arm Cortex-M1

The target CPU option is cortex-m1.

There are no relevant feature flags, and the FPU is not available.

thumbv7em-none-eabi and thumbv7em-none-eabihf

Tier: 2

Bare-metal target for CPUs in the Armv7E-M architecture family, supporting a subset of the T32 ISA.

Processors in this family include the:

• Arm Cortex-M4 and Arm Cortex-M4F
• Arm Cortex-M7 and Arm Cortex-M7F

See arm-none-eabi for information applicable to all arm-none-eabi targets, in particular the difference between the eabi and eabihf ABI.

Target maintainers

• Rust Embedded Devices Working Group Cortex-M Team, cortex-m@teams.rust-embedded.org

Target CPU and Target Feature options

See the bare-metal Arm docs for details on how to use these flags.

Table of supported CPUs for thumbv7em-none-eabi

Table of supported CPUs for thumbv7em-none-eabihf

Arm Cortex-M4 and Arm Cortex-M4F

The target CPU is cortex-m4.

• All Cortex-M4 have DSP extensions
  • support is controlled by the dsp target-feature
  • enabled by default with this target
• Cortex-M4F has a single precision FPU
  • support is enabled by default with this target-cpu
  • disable support using the -fpregs target-feature (eabi only)

Arm Cortex-M7 and Arm Cortex-M7F

The target CPU is cortex-m7.

• All Cortex-M7 have DSP extensions
  • support is controlled by the dsp target-feature
  • enabled by default with this target
• Cortex-M7F have either a single-precision or double-precision FPU
  • double-precision support is enabled by default with this target-cpu
    • opt-out by using the -f64 target-feature
  • disable support entirely using the -fpregs target-feature (eabi only)

thumbv7m-none-eabi

Tier: 2

Bare-metal target for CPUs in the Armv7-M architecture family, supporting a subset of the T32 ISA.

Processors in this family include the:

• Arm Cortex-M3

See arm-none-eabi for information applicable to all arm-none-eabi targets.

This target uses the soft-float ABI: functions which take f32 or f64 as arguments will have those values packed into integer registers. This is the only option because there is no FPU support in Armv7-M.

Target maintainers

• Rust Embedded Devices Working Group Cortex-M Team, cortex-m@teams.rust-embedded.org

Target CPU and Target Feature options

See the bare-metal Arm docs for details on how to use these flags.

Table of supported CPUs

Arm Cortex-M3

The target CPU option is cortex-m3.

There are no relevant feature flags, and the FPU is not available.

thumbv8m.base-none-eabi

Tier: 2

Bare-metal target for CPUs in the Baseline Armv8-M architecture family, supporting a subset of the T32 ISA.

Processors in this family include the:

• Arm Cortex-M23

See arm-none-eabi for information applicable to all arm-none-eabi targets.

This target uses the soft-float ABI: functions which take f32 or f64 as arguments will have those values packed into integer registers. This is the only option because there is no FPU support in Armv8-M Baseline.

Target maintainers

• Rust Embedded Devices Working Group Cortex-M Team, cortex-m@teams.rust-embedded.org

Target CPU and Target Feature options

See the bare-metal Arm docs for details on how to use these flags.

Table of supported CPUs

Arm Cortex-M23

The target CPU option is cortex-m23.

There are no relevant feature flags, and the FPU is not available.

thumbv8m.main-none-eabi and thumbv8m.main-none-eabihf

Tier: 2

Bare-metal target for CPUs in the Mainline Armv8-M architecture family, supporting a subset of the T32 ISA.

Processors in this family include the:

• Arm Cortex-M33
• Arm Cortex-M35P
• Arm Cortex-M55
• Arm Cortex-M85

See arm-none-eabi for information applicable to all arm-none-eabi targets, in particular the difference between the eabi and eabihf ABI.

Target maintainers

• Rust Embedded Devices Working Group Cortex-M Team, cortex-m@teams.rust-embedded.org

Target CPU and Target Feature options

See the bare-metal Arm docs for details on how to use these flags.

Table of supported CPUs for thumbv8m.main-none-eabi

Table of supported CPUs for thumbv8m.main-none-eabihf

Technically you can use this hard-float ABI on a CPU which has no FPU but does have Integer MVE, because MVE provides the same set of registers as the FPU (including s0 and d0). The particular set of flags that might enable this unusual scenario are currently not recorded here.

Arm Cortex-M33

The target CPU is cortex-m33.

• Has optional DSP extensions
  • support is controlled by the dsp target-feature
  • enabled by default with this target-cpu
• Has an optional single precision FPU
  • support is enabled by default with this target-cpu
  • disable support using the -fpregs target-feature (eabi only)

Arm Cortex-M35P

The target CPU is cortex-m35p.

• Has optional DSP extensions
  • support is controlled by the dsp target-feature
  • enabled by default with this target-cpu
• Has an optional single precision FPU
  • support is enabled by default with this target-cpu
  • disable support using the -fpregs target-feature (eabi only)

Arm Cortex-M55

The target CPU is cortex-m55.

• Has DSP extensions
  • support is controlled by the dsp target-feature
  • enabled by default with this target-cpu
• Has an optional double-precision FPU that also supports half-precision FP16 values
  • support is enabled by default with this target-cpu
  • disable support using the -fpregs target-feature (eabi only)
• Has optional support for M-Profile Vector Extensions
  • Also known as Helium Technology
  • Available with only integer support, or both integer/float support
  • The appropriate feature for the MVE is either mve (integer) or mve.fp (float)
  • mve.fp is enabled by default on this target CPU
  • disable using -mve.fp (disable float MVE) or -mve (disable all MVE)

Arm Cortex-M85

The target CPU is cortex-m85.

• Has DSP extensions
  • support is controlled by the dsp target-feature
  • enabled by default with this target-cpu
• Has an optional double-precision FPU that also supports half-precision FP16 values
  • support is enabled by default with this target-cpu
  • disable support using the -fpregs target-feature (eabi only)
• Has optional support for M-Profile Vector Extensions
  • Also known as Helium Technology
  • Available with only integer support, or both integer/float support
  • The appropriate feature for the MVE is either mve (integer) or mve.fp (float)
  • mve.fp is enabled by default on this target CPU
  • disable using -mve.fp (disable float MVE) or -mve (disable all MVE)

armv6k-nintendo-3ds

Tier: 3

The Nintendo 3DS platform, which has an Armv6k processor, and its associated operating system (horizon).

Rust support for this target is not affiliated with Nintendo, and is not derived from nor used with any official Nintendo SDK.

Target maintainers

This target is maintained by members of the @rust3ds organization:

• @Meziu
• @AzureMarker
• @ian-h-chamberlain

Requirements

This target is cross-compiled. Dynamic linking is not supported.

#![no_std] crates can be built using build-std to build core and optionally alloc, and either panic_abort or panic_unwind.

std is partially supported, but mostly works. Some APIs are unimplemented and will simply return an error, such as std::process. An allocator is provided by default.

In order to support some APIs, binaries must be linked against libc written for the target, using a linker for the target. These are provided by the devkitARM toolchain. See Cross-compilation toolchains and C code for more details.

Additionally, some helper crates provide implementations of some libc functions use by std that may otherwise be missing. These, or an alternate implementation of the relevant functions, are required to use std:

• pthread-3ds provides pthread APIs for std::thread.
• shim-3ds fulfills some other missing libc APIs (e.g. getrandom).

Binaries built for this target should be compatible with all variants of the 3DS (and 2DS) hardware and firmware, but testing is limited and some versions may not work correctly.

This target generates binaries in the ELF format.

Building the target

You can build Rust with support for the target by adding it to the target list in config.toml and providing paths to the devkitARM toolchain.

[build]
build-stage = 1
target = ["armv6k-nintendo-3ds"]

[target.armv6k-nintendo-3ds]
cc = "/opt/devkitpro/devkitARM/bin/arm-none-eabi-gcc"
cxx = "/opt/devkitpro/devkitARM/bin/arm-none-eabi-g++"
ar = "/opt/devkitpro/devkitARM/bin/arm-none-eabi-ar"
ranlib = "/opt/devkitpro/devkitARM/bin/arm-none-eabi-ranlib"
linker = "/opt/devkitpro/devkitARM/bin/arm-none-eabi-gcc"

Also, to build compiler_builtins for the target, export these flags before building the Rust toolchain:

export CFLAGS_armv6k_nintendo_3ds="-mfloat-abi=hard -mtune=mpcore -mtp=soft -march=armv6k"

Building Rust programs

Rust does not yet ship pre-compiled artifacts for this target.

The recommended way to build binaries is by using the cargo-3ds tool, which uses build-std and provides commands that work like the usual cargo run, cargo build, etc. The cargo 3ds new will automatically set up a new project with the dependencies needed to build a simple binary.

You can also build Rust with the target enabled (see Building the target above).

As mentioned in Requirements, programs that use std must link against both the devkitARM toolchain and libraries providing the libc APIs used in std. There is a general-purpose utility crate for working with nonstandard APIs provided by the OS: ctru-rs. Add it to Cargo.toml to use it in your program:

[dependencies]
ctru-rs = { git = "https://github.com/rust3ds/ctru-rs.git" }

Depending on ctru-rs ensures that all the necessary symbols are available at link time.

Testing

Binaries built for this target can be run in an emulator (most commonly Citra), or sent to a device through the use of a tool like devkitARM's 3dslink. They may also simply be copied to an SD card to be inserted in the device.

The cargo-3ds tool mentioned in Building Rust programs supports the use of 3dslink with cargo 3ds run. The default Rust test runner is not supported, but custom test frameworks can be used with cargo 3ds test to run unit tests on a device.

The Rust test suite for library/std is not yet supported.

Cross-compilation toolchains and C code

C code can be built for this target using the devkitARM toolchain. This toolchain provides arm-none-eabi-gcc as the linker used to link Rust programs as well.

The toolchain also provides a libc implementation, which is required by std for many of its APIs, and a helper library libctru which is used by several of the helper crates listed in Requirements. This toolchain does not, however, include all of the APIs expected by std, and the remaining APIs are implemented by pthread-3ds and linker-fix-3ds.

armv7-rtems-eabihf

Tier: 3

ARM targets for the RTEMS realtime operating system using the RTEMS gcc cross-compiler for linking against the libraries of a specified Board Support Package (BSP).

Target maintainers

• @thesummer

Requirements

The target does not support host tools. Only cross-compilation is possible. The cross-compiler toolchain can be obtained by following the installation instructions of the RTEMS Documentation. Additionally to the cross-compiler also a compiled BSP for a board fitting the architecture needs to be available on the host. Currently tested has been the BSP xilinx_zynq_a9_qemu of RTEMS 6.

std support is available, but not yet fully tested. Do NOT use in flight software!

The target follows the EABI calling convention for extern "C".

The resulting binaries are in ELF format.

Building the target

The target can be built by the standard compiler of Rust.

Building Rust programs

Rust does not yet ship pre-compiled artifacts for this target. To compile for this target, you will either need to build Rust with the target enabled (see "Building the target" above), or build your own copy of core by using build-std or similar.

In order to build an RTEMS executable it is also necessary to have a basic RTEMS configuration (in C) compiled to link against as this configures the operating system. An example can be found at this rtems-sys crate which could be added as an dependency to your application.

Testing

The resulting binaries run fine on an emulated target (possibly also on a real Zedboard or similar). For example, on qemu the following command can execute the binary:

qemu-system-arm -no-reboot -serial null -serial mon:stdio -net none -nographic -M xilinx-zynq-a9 -m 512M -kernel <binary file>

While basic execution of the unit test harness seems to work. However, running the Rust testsuite on the (emulated) hardware has not yet been tested.

Cross-compilation toolchains and C code

Compatible C-code can be built with the RTEMS cross-compiler toolchain arm-rtems6-gcc. For more information how to build the toolchain, RTEMS itself and RTEMS applications please have a look at the RTEMS Documentation.

armv7-sony-vita-newlibeabihf

Tier: 3

This tier supports the ARM Cortex A9 processor running on a PlayStation Vita console.

Rust support for this target is not affiliated with Sony, and is not derived from nor used with any official Sony SDK.

Target maintainers

• @nikarh
• @pheki
• @ZetaNumbers

Requirements

This target is cross-compiled, and requires installing VITASDK toolchain on your system. Dynamic linking is not supported.

#![no_std] crates can be built using build-std to build core, and optionally alloc, and panic_abort.

std is partially supported, but mostly works. Some APIs are unimplemented and will simply return an error, such as std::process.

This target generates binaries in the ELF format with thumb ISA by default.

Binaries are linked with arm-vita-eabi-gcc provided by VITASDK toolchain.

Building the target

Rust does not ship pre-compiled artifacts for this target. You can use build-std flag to build ELF binaries with std:

cargo build -Z build-std=std,panic_abort --target=armv7-sony-vita-newlibeabihf --release

Building Rust programs

The recommended way to build artifacts that can be installed and run on PlayStation Vita is by using the cargo-vita tool. This tool uses build-std and VITASDK toolchain to build artifacts runnable on Vita.

To install the tool run:

cargo install cargo-vita

VITASDK toolchain must be installed, and the VITASDK environment variable must be set to its location, e.g.:

export VITASDK=/opt/vitasdk

Add the following section to your project's Cargo.toml:

[package.metadata.vita]
# A unique 9 character alphanumeric identifier of the app.
title_id = "RUSTAPP01"
# A title that will be used for the app. Optional, name will be used if not defined
title_name = "My application"

To build a VPK with ELF in the release profile, run:

cargo vita build vpk --release

After building a *.vpk file it can be uploaded to a PlayStation Vita and installed, or used with a Vita3K emulator.

Testing

The default Rust test runner is supported, and tests can be compiled to an elf and packed to a *.vpk file using cargo-vita tool. Filtering tests is not currently supported since passing command-line arguments to the executable is not supported on Vita, so the runner will always execute all tests.

The Rust test suite for library/std is not yet supported.

Cross-compilation

This target can be cross-compiled from x86_64 on Windows, MacOS or Linux systems. Other hosts are not supported for cross-compilation.

armv7-unknown-linux-uclibceabi

Tier: 3

This target supports Armv7-A softfloat CPUs and uses the uclibc-ng standard library. This is a common configuration on many consumer routers (e.g., Netgear R7000, Asus RT-AC68U).

Target maintainers

• @lancethepants

Requirements

This target is cross compiled, and requires a cross toolchain.

This target supports host tools and std.

Building the target

You will need to download or build a 'C' cross toolchain that targets Armv7-A softfloat and that uses the uclibc-ng standard library. If your target hardware is something like a router or an embedded device, keep in mind that manufacturer supplied SDKs for this class of CPU could be outdated and potentially unsuitable for bootstrapping rust.

Here is a sample toolchain that is built using buildroot. It uses modern toolchain components, older thus universal kernel headers (2.6.36.4), and is used for a project called Tomatoware. This toolchain is patched so that its sysroot is located at /mmc (e.g., /mmc/bin, /mmc/lib, /mmc/include). This is useful in scenarios where the root filesystem is read-only but you are able attach external storage loaded with user applications. Tomatoware is an example of this that even allows you to run various compilers and developer tools natively on the target device.

Utilizing the Tomatoware toolchain this target can be built for cross compilation and native compilation (host tools) with project

rust-bootstrap-armv7-unknown-linux-uclibceabi.

Here is a sample config if using your own toolchain.

[build]
build-stage = 2
target = ["armv7-unknown-linux-uclibceabi"]

[target.armv7-unknown-linux-uclibceabi]
cc = "/path/to/arm-unknown-linux-uclibcgnueabi-gcc"
cxx = "/path/to/arm-unknown-linux-uclibcgnueabi-g++"
ar = "path/to/arm-unknown-linux-uclibcgnueabi-ar"
ranlib = "path/to/arm-unknown-linux-uclibcgnueabi-ranlib"
linker = "/path/to/arm-unknown-linux-uclibcgnueabi-gcc"

Building Rust programs

The following assumes you are using the Tomatoware toolchain and environment. Adapt if you are using your own toolchain.

Native compilation

Since this target supports host tools, you can natively build rust applications directly on your target device. This can be convenient because it removes the complexities of cross compiling and you can immediately test and deploy your binaries. One downside is that compiling on your Armv7-A CPU will probably be much slower than cross compilation on your x86 machine.

To setup native compilation:

• Download Tomatoware to your device using the latest nightly release found here.
• Extract tar zxvf arm-soft-mmc.tgz -C /mmc
• Add /mmc/bin:/mmc:sbin/ to your PATH, or source /mmc/etc/profile
• apt update && apt install rust

If you bootstrap rust on your own using the project above, it will create a .deb file that you then can install with

dpkg -i rust_1.xx.x-x_arm.deb

After completing these steps you can use rust normally in a native environment.

Cross Compilation

To cross compile, you'll need to:

• Build the rust cross toolchain using rust-bootstrap-armv7-unknown-linux-uclibceabi or your own built toolchain.

• Link your built toolchain with

  rustup toolchain link stage2 \
  ${HOME}/rust-bootstrap-armv7-unknown-linux-uclibceabi/src/rust/rust/build/x86_64-unknown-linux-gnu/stage2
  

• Build with:

  CC_armv7_unknown_linux_uclibceabi=/opt/tomatoware/arm-soft-mmc/bin/arm-linux-gcc \
  CXX_armv7_unknown_linux_uclibceabi=/opt/tomatoware/arm-soft-mmc/bin/arm-linux-g++ \
  AR_armv7_unknown_linux_uclibceabi=/opt/tomatoware/arm-soft-mmc/bin/arm-linux-ar \
  CFLAGS_armv7_unknown_linux_uclibceabi="-march=armv7-a -mtune=cortex-a9" \
  CXXFLAGS_armv7_unknown_linux_uclibceabi="-march=armv7-a -mtune=cortex-a9" \
  CARGO_TARGET_ARMV7_UNKNOWN_LINUX_UCLIBCEABI_LINKER=/opt/tomatoware/arm-soft-mmc/bin/arm-linux-gcc \
  CARGO_TARGET_ARMV7_UNKNOWN_LINUX_UCLIBCEABI_RUSTFLAGS='-Clink-arg=-s -Clink-arg=-Wl,--dynamic-linker=/mmc/lib/ld-uClibc.so.1 -Clink-arg=-Wl,-rpath,/mmc/lib' \
  cargo +stage2 \
  build \
  --target armv7-unknown-linux-uclibceabi \
  --release
  

• Copy the binary to your target device and run.

We specify CC, CXX, AR, CFLAGS, and CXXFLAGS environment variables because sometimes a project or a subproject requires the use of your 'C' cross toolchain. Since Tomatoware has a modified sysroot we also pass via RUSTFLAGS the location of the dynamic-linker and rpath.

Test with QEMU

To test a cross-compiled binary on your build system follow the instructions for Cross Compilation, install qemu-arm-static, and run with the following.

CC_armv7_unknown_linux_uclibceabi=/opt/tomatoware/arm-soft-mmc/bin/arm-linux-gcc \
CXX_armv7_unknown_linux_uclibceabi=/opt/tomatoware/arm-soft-mmc/bin/arm-linux-g++ \
AR_armv7_unknown_linux_uclibceabi=/opt/tomatoware/arm-soft-mmc/bin/arm-linux-ar \
CFLAGS_armv7_unknown_linux_uclibceabi="-march=armv7-a -mtune=cortex-a9" \
CXXFLAGS_armv7_unknown_linux_uclibceabi="-march=armv7-a -mtune=cortex-a9" \
CARGO_TARGET_ARMV7_UNKNOWN_LINUX_UCLIBCEABI_LINKER=/opt/tomatoware/arm-soft-mmc/bin/arm-linux-gcc \
CARGO_TARGET_ARMV7_UNKNOWN_LINUX_UCLIBCEABI_RUNNER="qemu-arm-static -L /opt/tomatoware/arm-soft-mmc/arm-tomatoware-linux-uclibcgnueabi/sysroot/" \
cargo +stage2 \
run \
--target armv7-unknown-linux-uclibceabi \
--release

Run in a chroot

It's also possible to build in a chroot environment. This is a convenient way to work without needing to access the target hardware.

To build the chroot:

• sudo debootstrap --arch armel bullseye $HOME/debian
• sudo chroot $HOME/debian/ /bin/bash
• mount proc /proc -t proc
• mount -t sysfs /sys sys/
• export PATH=/mmc/bin:/mmc/sbin:$PATH

From here you can setup your environment (e.g., add user, install wget).

• Download Tomatoware to the chroot environment using the latest nightly release found here.
• Extract tar zxvf arm-soft-mmc.tgz -C /mmc
• Add /mmc/bin:/mmc:sbin/ to your PATH, or source /mmc/etc/profile
• sudo /mmc/bin/apt update && sudo /mmc/bin/apt install rust

After completing these steps you can use rust normally in a chroot environment.

Remember when using sudo the root user's PATH could differ from your user's PATH.

armv7-unknown-linux-uclibceabihf

Tier: 3

This tier supports the Armv7-A processor running a Linux kernel and uClibc-ng standard library. It provides full support for rust and the rust standard library.

Designated Developers

• @skrap

Requirements

This target is cross compiled, and requires a cross toolchain. You can find suitable pre-built toolchains at bootlin or build one yourself via buildroot.

Building

Get a C toolchain

Compiling rust for this target has been tested on x86_64 linux hosts. Other host types have not been tested, but may work, if you can find a suitable cross compilation toolchain for them.

If you don't already have a suitable toolchain, download one here, and unpack it into a directory.

Configure rust

The target can be built by enabling it for a rustc build, by placing the following in config.toml:

[build]
target = ["armv7-unknown-linux-uclibceabihf"]
stage = 2

[target.armv7-unknown-linux-uclibceabihf]
# ADJUST THIS PATH TO POINT AT YOUR TOOLCHAIN
cc = "/TOOLCHAIN_PATH/bin/arm-buildroot-linux-uclibcgnueabihf-gcc"

Build

# in rust dir
./x.py build --stage 2

Building and Running Rust Programs

To test cross-compiled binaries on a x86_64 system, you can use the qemu-arm userspace emulation program. This avoids having a full emulated ARM system by doing dynamic binary translation and dynamic system call translation. It lets you run ARM programs directly on your x86_64 kernel. It's very convenient!

To use:

• Install qemu-arm according to your distro.
• Link your built toolchain via:
  • rustup toolchain link stage2 ${RUST}/build/x86_64-unknown-linux-gnu/stage2
• Create a test program

cargo new hello_world
cd hello_world

• Build and run

CARGO_TARGET_ARMV7_UNKNOWN_LINUX_UCLIBCEABIHF_RUNNER="qemu-arm -L ${TOOLCHAIN}/arm-buildroot-linux-uclibcgnueabihf/sysroot/" \
CARGO_TARGET_ARMV7_UNKNOWN_LINUX_UCLIBCEABIHF_LINKER=${TOOLCHAIN}/bin/arm-buildroot-linux-uclibcgnueabihf-gcc \
cargo +stage2 run --target armv7-unknown-linux-uclibceabihf

*-linux-android and *-linux-androideabi

Tier: 2

Android is a mobile operating system built on top of the Linux kernel.

Target maintainers

• Chris Wailes (@chriswailes)
• Matthew Maurer (@maurer)
• Martin Geisler (@mgeisler)

Requirements

This target is cross-compiled from a host environment. Development may be done from the source tree or using the Android NDK.

Android targets support std. Generated binaries use the ELF file format.

NDK/API Update Policy

Rust will support the most recent Long Term Support (LTS) Android Native Development Kit (NDK). By default Rust will support all API levels supported by the NDK, but a higher minimum API level may be required if deemed necessary.

Building the target

To build Rust binaries for Android you'll need a copy of the most recent LTS edition of the Android NDK. Supported Android targets are:

• aarch64-linux-android
• arm-linux-androideabi
• armv7-linux-androideabi
• i686-linux-android
• thumbv7neon-linux-androideabi
• x86_64-linux-android

The riscv64-linux-android target is supported as a Tier 3 target.

A list of all supported targets can be found here

Architecture Notes

riscv64-linux-android

Currently the riscv64-linux-android target requires the following architecture features/extensions:

• a (atomics)
• d (double-precision floating-point)
• c (compressed instruction set)
• f (single-precision floating-point)
• m (multiplication and division)
• v (vector)
• Zba (address calculation instructions)
• Zbb (base instructions)
• Zbs (single-bit instructions)

aarch64-linux-android on Nightly compilers

As soon as -Zfixed-x18 compiler flag is supplied, the ShadowCallStack sanitizer instrumentation is also made available by supplying the second compiler flag -Zsanitizer=shadow-call-stack.

*-unknown-linux-ohos

Tier: 2

• aarch64-unknown-linux-ohos
• armv7-unknown-linux-ohos
• x86_64-unknown-linux-ohos

Tier: 3

• loongarch64-unknown-linux-ohos

Targets for the OpenHarmony operating system.

Target maintainers

• Amanieu d'Antras (@Amanieu)
• Lu Binglun (@lubinglun)

Setup

The OpenHarmony SDK doesn't currently support Rust compilation directly, so some setup is required.

First, you must obtain the OpenHarmony SDK from this page. Select the version of OpenHarmony you are developing for and download the "Public SDK package for the standard system".

Create the following shell scripts that wrap Clang from the OpenHarmony SDK:

aarch64-unknown-linux-ohos-clang.sh

#!/bin/sh
exec /path/to/ohos-sdk/linux/native/llvm/bin/clang \
  -target aarch64-linux-ohos \
  --sysroot=/path/to/ohos-sdk/linux/native/sysroot \
  -D__MUSL__ \
  "$@"

aarch64-unknown-linux-ohos-clang++.sh

#!/bin/sh
exec /path/to/ohos-sdk/linux/native/llvm/bin/clang++ \
  -target aarch64-linux-ohos \
  --sysroot=/path/to/ohos-sdk/linux/native/sysroot \
  -D__MUSL__ \
  "$@"

armv7-unknown-linux-ohos-clang.sh

#!/bin/sh
exec /path/to/ohos-sdk/linux/native/llvm/bin/clang \
  -target arm-linux-ohos \
  --sysroot=/path/to/ohos-sdk/linux/native/sysroot \
  -D__MUSL__ \
  -march=armv7-a \
  -mfloat-abi=softfp \
  -mtune=generic-armv7-a \
  -mthumb \
  "$@"

armv7-unknown-linux-ohos-clang++.sh

#!/bin/sh
exec /path/to/ohos-sdk/linux/native/llvm/bin/clang++ \
  -target arm-linux-ohos \
  --sysroot=/path/to/ohos-sdk/linux/native/sysroot \
  -D__MUSL__ \
  -march=armv7-a \
  -mfloat-abi=softfp \
  -mtune=generic-armv7-a \
  -mthumb \
  "$@"

x86_64-unknown-linux-ohos-clang.sh

#!/bin/sh
exec /path/to/ohos-sdk/linux/native/llvm/bin/clang \
  -target x86_64-linux-ohos \
  --sysroot=/path/to/ohos-sdk/linux/native/sysroot \
  -D__MUSL__ \
  "$@"

x86_64-unknown-linux-ohos-clang++.sh

#!/bin/sh
exec /path/to/ohos-sdk/linux/native/llvm/bin/clang++ \
  -target x86_64-linux-ohos \
  --sysroot=/path/to/ohos-sdk/linux/native/sysroot \
  -D__MUSL__ \
  "$@"

Future versions of the OpenHarmony SDK will avoid the need for this process.

Building Rust programs

Rustup ships pre-compiled artifacts for this target, which you can install with:

rustup target add aarch64-unknown-linux-ohos
rustup target add armv7-unknown-linux-ohos
rustup target add x86_64-unknown-linux-ohos

You will need to configure the linker to use in ~/.cargo/config.toml:

[target.aarch64-unknown-linux-ohos]
ar = "/path/to/ohos-sdk/linux/native/llvm/bin/llvm-ar"
linker = "/path/to/aarch64-unknown-linux-ohos-clang.sh"

[target.armv7-unknown-linux-ohos]
ar = "/path/to/ohos-sdk/linux/native/llvm/bin/llvm-ar"
linker = "/path/to/armv7-unknown-linux-ohos-clang.sh"

[target.x86_64-unknown-linux-ohos]
ar = "/path/to/ohos-sdk/linux/native/llvm/bin/llvm-ar"
linker = "/path/to/x86_64-unknown-linux-ohos-clang.sh"

Building the target from source

Instead of using rustup, you can instead build a rust toolchain from source. Create a config.toml with the following contents:

profile = "compiler"
change-id = 115898

[build]
sanitizers = true
profiler = true

[target.aarch64-unknown-linux-ohos]
cc = "/path/to/aarch64-unknown-linux-ohos-clang.sh"
cxx = "/path/to/aarch64-unknown-linux-ohos-clang++.sh"
ar = "/path/to/ohos-sdk/linux/native/llvm/bin/llvm-ar"
ranlib = "/path/to/ohos-sdk/linux/native/llvm/bin/llvm-ranlib"
linker  = "/path/to/aarch64-unknown-linux-ohos-clang.sh"

[target.armv7-unknown-linux-ohos]
cc = "/path/to/armv7-unknown-linux-ohos-clang.sh"
cxx = "/path/to/armv7-unknown-linux-ohos-clang++.sh"
ar = "/path/to/ohos-sdk/linux/native/llvm/bin/llvm-ar"
ranlib = "/path/to/ohos-sdk/linux/native/llvm/bin/llvm-ranlib"
linker  = "/path/to/armv7-unknown-linux-ohos-clang.sh"

[target.x86_64-unknown-linux-ohos]
cc = "/path/to/x86_64-unknown-linux-ohos-clang.sh"
cxx = "/path/to/x86_64-unknown-linux-ohos-clang++.sh"
ar = "/path/to/ohos-sdk/linux/native/llvm/bin/llvm-ar"
ranlib = "/path/to/ohos-sdk/linux/native/llvm/bin/llvm-ranlib"
linker  = "/path/to/x86_64-unknown-linux-ohos-clang.sh"

Testing

Running the Rust testsuite is possible, but currently difficult due to the way the OpenHarmony emulator is set up (no networking).

Cross-compilation toolchains and C code

You can use the shell scripts above to compile C code for the target.

i686-unknown-hurd-gnu and x86_64-unknown-hurd-gnu

Tier: 3

[GNU/Hurd] is the GNU Hurd is the GNU project's replacement for the Unix kernel.

Target maintainers

• Samuel Thibault, samuel.thibault@ens-lyon.org, https://github.com/sthibaul/

Requirements

The target supports host tools.

The GNU/Hurd target supports std and uses the standard ELF file format.

Building the target

This target can be built by adding i686-unknown-hurd-gnu and x86_64-unknown-hurd-gnu as targets in the rustc list.

Building Rust programs

Rust does not yet ship pre-compiled artifacts for this target. To compile for this target, you will either need to build Rust with the target enabled (see "Building the target" above), or build your own copy of core by using build-std or similar.

Testing

Tests can be run in the same way as a regular binary.

Cross-compilation toolchains and C code

The target supports C code, the GNU toolchain calls the target i686-unknown-gnu and x86_64-unknown-gnu.

aarch64-unknown-teeos

Tier: 3

Target for the TEEOS operating system.

TEEOS is a mini os run in TrustZone, for trusted/security apps. The kernel of TEEOS is HongMeng/ChCore micro kernel. The libc for TEEOS is a part of musl. It's very small that there is no RwLock, no network, no stdin, and no file system for apps in TEEOS.

Some abbreviation:

TEEOS is open source in progress. MORE about

Target maintainers

• Petrochenkov Vadim
• Sword-Destiny

Setup

We use OpenHarmony SDK for TEEOS.

The OpenHarmony SDK doesn't currently support Rust compilation directly, so some setup is required.

First, you must obtain the OpenHarmony SDK from this page. Select the version of OpenHarmony you are developing for and download the "Public SDK package for the standard system".

Create the following shell scripts that wrap Clang from the OpenHarmony SDK:

aarch64-unknown-teeos-clang.sh

#!/bin/sh
exec /path/to/ohos-sdk/linux/native/llvm/bin/clang \
  -target aarch64-linux-gnu \
  "$@"

aarch64-unknown-teeos-clang++.sh

#!/bin/sh
exec /path/to/ohos-sdk/linux/native/llvm/bin/clang++ \
  -target aarch64-linux-gnu \
  "$@"

Building the target

To build a rust toolchain, create a config.toml with the following contents:

profile = "compiler"
change-id = 115898

[build]
sanitizers = true
profiler = true
target = ["x86_64-unknown-linux-gnu", "aarch64-unknown-teeos"]
submodules = false
compiler-docs = false
extended = true

[install]
bindir = "bin"
libdir = "lib"

[target.aarch64-unknown-teeos]
cc = "/path/to/scripts/aarch64-unknown-teeos-clang.sh"
cxx = "/path/to/scripts/aarch64-unknown-teeos-clang.sh"
linker = "/path/to/scripts/aarch64-unknown-teeos-clang.sh"
ar = "/path/to/ohos-sdk/linux/native/llvm/bin/llvm-ar"
ranlib = "/path/to/ohos-sdk/linux/native/llvm/bin/llvm-ranlib"
llvm-config = "/path/to/ohos-sdk/linux/native/llvm/bin/llvm-config"

note: You need to insert "/usr/include/x86_64-linux-gnu/" into environment variable: $C_INCLUDE_PATH
 if some header files like bits/xxx.h not found.
note: You can install gcc-aarch64-linux-gnu,g++-aarch64-linux-gnu if some files like crti.o not found.
note: You may need to install libc6-dev-i386 libc6-dev if "gnu/stubs-32.h" not found.

Building Rust programs

Rust does not yet ship pre-compiled artifacts for this target. To compile for this target, you will either need to build Rust with the target enabled (see "Building the target" above), or build your own copy of core by using build-std or similar.

You will need to configure the linker to use in ~/.cargo/config:

[target.aarch64-unknown-teeos]
linker = "/path/to/aarch64-unknown-teeos-clang.sh" # or aarch64-linux-gnu-ld

Testing

Running the Rust testsuite is not possible now.

More information about how to test CA/TA. See here

*-espidf

Tier: 3

Targets for the ESP-IDF development framework running on RISC-V and Xtensa CPUs.

Target maintainers

• Ivan Markov @ivmarkov
• Scott Mabin @MabezDev
• Sergio Gasquez @SergioGasquez

Requirements

The target names follow this format: $ARCH-esp-espidf, where $ARCH specifies the target processor architecture. The following targets are currently defined:

It is recommended to use the latest ESP-IDF stable release if possible.

Building the target

The target can be built by enabling it for a rustc build. The build-std feature is required to build the standard library for ESP-IDF. ldproxy is also required for linking, it can be installed from crates.io.

[build]
target = ["$ARCH-esp-espidf"]

[target.$ARCH-esp-espidf]
linker = "ldproxy"

[unstable]
build-std = ["std", "panic_abort"]

The esp-idf-sys crate will handle the compilation of ESP-IDF, including downloading the relevant toolchains for the build.

Cross-compilation toolchains and C code

esp-idf-sys exposes the toolchain used in the compilation of ESP-IDF, see the crate documentation for build output propagation for more information.

aarch64-unknown-fuchsia and x86_64-unknown-fuchsia

Tier: 2

Fuchsia is a modern open source operating system that's simple, secure, updatable, and performant.

Target maintainers

See fuchsia.toml in the team repository for current target maintainers.

Table of contents

1. Requirements
2. Walkthrough structure
3. Compiling a Rust binary targeting Fuchsia
   1. Targeting Fuchsia with rustup and cargo
   2. Targeting Fuchsia with a compiler built from source
4. Creating a Fuchsia package
   1. Creating a Fuchsia component
   2. Building a Fuchsia package
5. Publishing a Fuchsia package
   1. Creating a Fuchsia package repository
   2. Publishing Fuchsia package to repository
6. Running a Fuchsia component on an emulator
   1. Starting the Fuchsia emulator
   2. Watching emulator logs
   3. Serving a Fuchsia package
   4. Running a Fuchsia component
7. .gitignore extensions
8. Testing
   1. Running unit tests
   2. Running the compiler test suite
9. Debugging
   1. zxdb
   2. Attaching zxdb
   3. Using zxdb
   4. Displaying source code in zxdb

Requirements

This target is cross-compiled from a host environment. You will need a recent copy of the Fuchsia SDK, which provides the tools, libraries, and binaries required to build and link programs for Fuchsia.

Development may also be done from the source tree.

Fuchsia targets support std and follow the sysv64 calling convention on x86_64. Fuchsia binaries use the ELF file format.

Walkthrough structure

This walkthrough will cover:

1. Compiling a Rust binary targeting Fuchsia.
2. Building a Fuchsia package.
3. Publishing and running a Fuchsia package to a Fuchsia emulator.

For the purposes of this walkthrough, we will only target x86_64-unknown-fuchsia.

Compiling a Rust binary targeting Fuchsia

Today, there are two main ways to build a Rust binary targeting Fuchsia using the Fuchsia SDK:

1. Allow rustup to handle the installation of Fuchsia targets for you.
2. Build a toolchain locally that can target Fuchsia.

Targeting Fuchsia with rustup and cargo

The easiest way to build a Rust binary targeting Fuchsia is by allowing rustup to handle the installation of Fuchsia targets for you. This can be done by issuing the following commands:

rustup target add x86_64-unknown-fuchsia
rustup target add aarch64-unknown-fuchsia

After installing our Fuchsia targets, we can now compile a Rust binary that targets Fuchsia.

To create our Rust project, we can use cargo as follows:

From base working directory

cargo new hello_fuchsia

The rest of this walkthrough will take place from hello_fuchsia, so we can change into that directory now:

cd hello_fuchsia

Note: From this point onwards, all commands will be issued from the hello_fuchsia/ directory, and all hello_fuchsia/ prefixes will be removed from references for sake of brevity.

We can edit our src/main.rs to include a test as follows:

src/main.rs

fn main() {
    println!("Hello Fuchsia!");
}

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

In addition to the standard workspace created, we will want to create a .cargo/config.toml file to link necessary libraries during compilation:

.cargo/config.toml

[target.x86_64-unknown-fuchsia]

rustflags = [
    "-Lnative=<SDK_PATH>/arch/x64/lib",
    "-Lnative=<SDK_PATH>/arch/x64/sysroot/lib"
]

Note: Make sure to fill out <SDK_PATH> with the path to the downloaded Fuchsia SDK.

These options configure the following:

• -Lnative=${SDK_PATH}/arch/${ARCH}/lib: Link against Fuchsia libraries from the SDK
• -Lnative=${SDK_PATH}/arch/${ARCH}/sysroot/lib: Link against Fuchsia sysroot libraries from the SDK

In total, our new project will look like:

Current directory structure

hello_fuchsia/
┣━ src/
┃  ┗━ main.rs
┣━ Cargo.toml
┗━ .cargo/
   ┗━ config.toml

Finally, we can build our rust binary as:

cargo build --target x86_64-unknown-fuchsia

Now we have a Rust binary at target/x86_64-unknown-fuchsia/debug/hello_fuchsia, targeting our desired Fuchsia target.

Current directory structure

hello_fuchsia/
┣━ src/
┃  ┗━ main.rs
┣━ target/
┃  ┗━ x86_64-unknown-fuchsia/
┃     ┗━ debug/
┃        ┗━ hello_fuchsia
┣━ Cargo.toml
┗━ .cargo/
   ┗━ config.toml

Targeting Fuchsia with a compiler built from source

An alternative to the first workflow is to target Fuchsia by using rustc built from source.

Before building Rust for Fuchsia, you'll need a clang toolchain that supports Fuchsia as well. A recent version (14+) of clang should be sufficient to compile Rust for Fuchsia.

x86-64 and AArch64 Fuchsia targets can be enabled using the following configuration in config.toml:

[build]
target = ["<host_platform>", "aarch64-unknown-fuchsia", "x86_64-unknown-fuchsia"]

[rust]
lld = true

[llvm]
download-ci-llvm = false

[target.x86_64-unknown-fuchsia]
cc = "clang"
cxx = "clang++"

[target.aarch64-unknown-fuchsia]
cc = "clang"
cxx = "clang++"

Though not strictly required, you may also want to use clang for your host target as well:

[target.<host_platform>]
cc = "clang"
cxx = "clang++"

By default, the Rust compiler installs itself to /usr/local on most UNIX systems. You may want to install it to another location (e.g. a local install directory) by setting a custom prefix in config.toml:

[install]
# Make sure to use the absolute path to your install directory
prefix = "<RUST_SRC_PATH>/install"

Next, the following environment variables must be configured. For example, using a script we name config-env.sh:

# Configure this environment variable to be the path to the downloaded SDK
export SDK_PATH="<SDK path goes here>"

export CFLAGS_aarch64_unknown_fuchsia="--target=aarch64-unknown-fuchsia --sysroot=${SDK_PATH}/arch/arm64/sysroot -I${SDK_PATH}/pkg/fdio/include"
export CXXFLAGS_aarch64_unknown_fuchsia="--target=aarch64-unknown-fuchsia --sysroot=${SDK_PATH}/arch/arm64/sysroot -I${SDK_PATH}/pkg/fdio/include"
export LDFLAGS_aarch64_unknown_fuchsia="--target=aarch64-unknown-fuchsia --sysroot=${SDK_PATH}/arch/arm64/sysroot -L${SDK_PATH}/arch/arm64/lib"
export CARGO_TARGET_AARCH64_UNKNOWN_FUCHSIA_RUSTFLAGS="-C link-arg=--sysroot=${SDK_PATH}/arch/arm64/sysroot -Lnative=${SDK_PATH}/arch/arm64/sysroot/lib -Lnative=${SDK_PATH}/arch/arm64/lib"
export CFLAGS_x86_64_unknown_fuchsia="--target=x86_64-unknown-fuchsia --sysroot=${SDK_PATH}/arch/x64/sysroot -I${SDK_PATH}/pkg/fdio/include"
export CXXFLAGS_x86_64_unknown_fuchsia="--target=x86_64-unknown-fuchsia --sysroot=${SDK_PATH}/arch/x64/sysroot -I${SDK_PATH}/pkg/fdio/include"
export LDFLAGS_x86_64_unknown_fuchsia="--target=x86_64-unknown-fuchsia --sysroot=${SDK_PATH}/arch/x64/sysroot -L${SDK_PATH}/arch/x64/lib"
export CARGO_TARGET_X86_64_UNKNOWN_FUCHSIA_RUSTFLAGS="-C link-arg=--sysroot=${SDK_PATH}/arch/x64/sysroot -Lnative=${SDK_PATH}/arch/x64/sysroot/lib -Lnative=${SDK_PATH}/arch/x64/lib"

Finally, the Rust compiler can be built and installed:

(source config-env.sh && ./x.py install)

Once rustc is installed, we can create a new working directory to work from, hello_fuchsia along with hello_fuchsia/src:

mkdir hello_fuchsia
cd hello_fuchsia
mkdir src

Note: From this point onwards, all commands will be issued from the hello_fuchsia/ directory, and all hello_fuchsia/ prefixes will be removed from references for sake of brevity.

There, we can create a new file named src/hello_fuchsia.rs:

src/hello_fuchsia.rs

fn main() {
    println!("Hello Fuchsia!");
}

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

Current directory structure

hello_fuchsia/
┗━ src/
    ┗━ hello_fuchsia.rs

Using your freshly installed rustc, you can compile a binary for Fuchsia using the following options:

• --target x86_64-unknown-fuchsia/--target aarch64-unknown-fuchsia: Targets the Fuchsia platform of your choice
• -Lnative ${SDK_PATH}/arch/${ARCH}/lib: Link against Fuchsia libraries from the SDK
• -Lnative ${SDK_PATH}/arch/${ARCH}/sysroot/lib: Link against Fuchsia sysroot libraries from the SDK

Putting it all together:

# Configure these for the Fuchsia target of your choice
TARGET_ARCH="<x86_64-unknown-fuchsia|aarch64-unknown-fuchsia>"
ARCH="<x64|aarch64>"

rustc \
    --target ${TARGET_ARCH} \
    -Lnative=${SDK_PATH}/arch/${ARCH}/lib \
    -Lnative=${SDK_PATH}/arch/${ARCH}/sysroot/lib \
    --out-dir bin src/hello_fuchsia.rs

Current directory structure

hello_fuchsia/
┣━ src/
┃   ┗━ hello_fuchsia.rs
┗━ bin/
   ┗━ hello_fuchsia

Creating a Fuchsia package

Before moving on, double check your directory structure:

Current directory structure

hello_fuchsia/
┣━ src/                         (if using rustc)
┃   ┗━ hello_fuchsia.rs         ...
┣━ bin/                         ...
┃  ┗━ hello_fuchsia             ...
┣━ src/                         (if using cargo)
┃  ┗━ main.rs                   ...
┗━ target/                      ...
   ┗━ x86_64-unknown-fuchsia/   ...
      ┗━ debug/                 ...
         ┗━ hello_fuchsia       ...

With our Rust binary built, we can move to creating a Fuchsia package. On Fuchsia, a package is the unit of distribution for software. We'll need to create a new package directory where we will place files like our finished binary and any data it may need.

To start, make the pkg, and pkg/meta directories:

mkdir pkg
mkdir pkg/meta

Current directory structure

hello_fuchsia/
┗━ pkg/
   ┗━ meta/

Now, create the following files inside:

pkg/meta/package

{
  "name": "hello_fuchsia",
  "version": "0"
}

The package file describes our package's name and version number. Every package must contain one.

pkg/hello_fuchsia.manifest if using cargo

bin/hello_fuchsia=target/x86_64-unknown-fuchsia/debug/hello_fuchsia
lib/ld.so.1=<SDK_PATH>/arch/x64/sysroot/dist/lib/ld.so.1
lib/libfdio.so=<SDK_PATH>/arch/x64/dist/libfdio.so
meta/package=pkg/meta/package
meta/hello_fuchsia.cm=pkg/meta/hello_fuchsia.cm

pkg/hello_fuchsia.manifest if using rustc

bin/hello_fuchsia=bin/hello_fuchsia
lib/ld.so.1=<SDK_PATH>/arch/x64/sysroot/dist/lib/ld.so.1
lib/libfdio.so=<SDK_PATH>/arch/x64/dist/libfdio.so
meta/package=pkg/meta/package
meta/hello_fuchsia.cm=pkg/meta/hello_fuchsia.cm

Note: Relative manifest paths are resolved starting from the working directory of ffx. Make sure to fill out <SDK_PATH> with the path to the downloaded SDK.

The .manifest file will be used to describe the contents of the package by relating their location when installed to their location on the file system. The bin/hello_fuchsia= entry will be different depending on how your Rust binary was built, so choose accordingly.

Current directory structure

hello_fuchsia/
┗━ pkg/
   ┣━ meta/
   ┃  ┗━ package
   ┗━ hello_fuchsia.manifest

Creating a Fuchsia component

On Fuchsia, components require a component manifest written in Fuchsia's markup language called CML. The Fuchsia devsite contains an overview of CML and a reference for the file format. Here's a basic one that can run our single binary:

pkg/hello_fuchsia.cml

{
    include: [ "syslog/client.shard.cml" ],
    program: {
        runner: "elf",
        binary: "bin/hello_fuchsia",
    },
}

Current directory structure

hello_fuchsia/
┗━ pkg/
   ┣━ meta/
   ┃  ┗━ package
   ┣━ hello_fuchsia.manifest
   ┗━ hello_fuchsia.cml

Now we can compile that CML into a component manifest:

${SDK_PATH}/tools/${ARCH}/cmc compile \
    pkg/hello_fuchsia.cml \
    --includepath ${SDK_PATH}/pkg \
    -o pkg/meta/hello_fuchsia.cm

Note: --includepath tells the compiler where to look for includes from our CML. In our case, we're only using syslog/client.shard.cml.

Current directory structure

hello_fuchsia/
┗━ pkg/
   ┣━ meta/
   ┃  ┣━ package
   ┃  ┗━ hello_fuchsia.cm
   ┣━ hello_fuchsia.manifest
   ┗━ hello_fuchsia.cml

Building a Fuchsia package

Next, we'll build a package manifest as defined by our manifest:

${SDK_PATH}/tools/${ARCH}/ffx package build \
    --api-level $(${SDK_PATH}/tools/${ARCH}/ffx --machine json version | jq .tool_version.api_level) \
    --out pkg/hello_fuchsia_manifest \
    pkg/hello_fuchsia.manifest

This will produce pkg/hello_fuchsia_manifest/ which is a package manifest we can publish directly to a repository.

Current directory structure

hello_fuchsia/
┗━ pkg/
   ┣━ meta/
   ┃  ┣━ package
   ┃  ┗━ hello_fuchsia.cm
   ┣━ hello_fuchsia_manifest/
   ┃  ┗━ ...
   ┣━ hello_fuchsia.manifest
   ┣━ hello_fuchsia.cml
   ┗━ hello_fuchsia_package_manifest

We are now ready to publish the package.

Publishing a Fuchsia package

With our package and component manifests setup, we can now publish our package. The first step will be to create a Fuchsia package repository to publish to.

Creating a Fuchsia package repository

We can set up our repository with:

${SDK_PATH}/tools/${ARCH}/ffx repository create pkg/repo

Current directory structure

hello_fuchsia/
┗━ pkg/
   ┣━ meta/
   ┃  ┣━ package
   ┃  ┗━ hello_fuchsia.cm
   ┣━ hello_fuchsia_manifest/
   ┃  ┗━ ...
   ┣━ repo/
   ┃  ┗━ ...
   ┣━ hello_fuchsia.manifest
   ┣━ hello_fuchsia.cml
   ┗━ hello_fuchsia_package_manifest

Publishing Fuchsia package to repository

We can publish our new package to that repository with:

${SDK_PATH}/tools/${ARCH}/ffx repository publish \
    --package pkg/hello_fuchsia_package_manifest \
    pkg/repo

Running a Fuchsia component on an emulator

At this point, we are ready to run our Fuchsia component. For reference, our final directory structure will look like:

Final directory structure

hello_fuchsia/
┣━ src/                         (if using rustc)
┃   ┗━ hello_fuchsia.rs         ...
┣━ bin/                         ...
┃  ┗━ hello_fuchsia             ...
┣━ src/                         (if using cargo)
┃  ┗━ main.rs                   ...
┣━ target/                      ...
┃  ┗━ x86_64-unknown-fuchsia/   ...
┃     ┗━ debug/                 ...
┃        ┗━ hello_fuchsia       ...
┗━ pkg/
   ┣━ meta/
   ┃  ┣━ package
   ┃  ┗━ hello_fuchsia.cm
   ┣━ hello_fuchsia_manifest/
   ┃  ┗━ ...
   ┣━ repo/
   ┃  ┗━ ...
   ┣━ hello_fuchsia.manifest
   ┣━ hello_fuchsia.cml
   ┗━ hello_fuchsia_package_manifest

Starting the Fuchsia emulator

Start a Fuchsia emulator in a new terminal using:

${SDK_PATH}/tools/${ARCH}/ffx product-bundle get workstation_eng.qemu-${ARCH}
${SDK_PATH}/tools/${ARCH}/ffx emu start workstation_eng.qemu-${ARCH} --headless

Watching emulator logs

Once the emulator is running, open a separate terminal to watch the emulator logs:

In separate terminal

${SDK_PATH}/tools/${ARCH}/ffx log \
    --since now

Serving a Fuchsia package

Now, start a package repository server to serve our package to the emulator:

${SDK_PATH}/tools/${ARCH}/ffx repository server start \
    --background --repository hello-fuchsia --repo-path pkg-repo

Once the repository server is up and running, register it with the target Fuchsia system running in the emulator:

${SDK_PATH}/tools/${ARCH}/ffx target repository register \
    --repository hello-fuchsia

Running a Fuchsia component

Finally, run the component:

${SDK_PATH}/tools/${ARCH}/ffx component run \
    /core/ffx-laboratory:hello_fuchsia \
    fuchsia-pkg://hello-fuchsia/hello_fuchsia_manifest#meta/hello_fuchsia.cm

On reruns of the component, the --recreate argument may also need to be passed.

${SDK_PATH}/tools/${ARCH}/ffx component run \
    --recreate \
    /core/ffx-laboratory:hello_fuchsia \
    fuchsia-pkg://hello-fuchsia/hello_fuchsia_manifest#meta/hello_fuchsia.cm

.gitignore extensions

Optionally, we can create/extend our .gitignore file to ignore files and directories that are not helpful to track:

pkg/repo
pkg/meta/hello_fuchsia.cm
pkg/hello_fuchsia_manifest
pkg/hello_fuchsia_package_manifest

Testing

Running unit tests

Tests can be run in the same way as a regular binary.

• If using cargo, you can simply pass test --no-run to the cargo invocation and then repackage and rerun the Fuchsia package. From our previous example, this would look like cargo test --target x86_64-unknown-fuchsia --no-run, and moving the executable binary path found from the line Executable unittests src/main.rs (target/x86_64-unknown-fuchsia/debug/deps/hello_fuchsia-<HASH>) into pkg/hello_fuchsia.manifest.

• If using the compiled rustc, you can simply pass --test to the rustc invocation and then repackage and rerun the Fuchsia package.

The test harness will run the applicable unit tests.

Often when testing, you may want to pass additional command line arguments to your binary. Additional arguments can be set in the component manifest:

pkg/hello_fuchsia.cml

{
    include: [ "syslog/client.shard.cml" ],
    program: {
        runner: "elf",
        binary: "bin/hello_fuchsia",
        args: ["it_works"],
    },
}

This will pass the argument it_works to the binary, filtering the tests to only those tests that match the pattern. There are many more configuration options available in CML including environment variables. More documentation is available on the Fuchsia devsite.

Running the compiler test suite

The commands in this section assume that they are being run from inside your local Rust source checkout:

cd ${RUST_SRC_PATH}

To run the Rust test suite on an emulated Fuchsia device, you'll also need to download a copy of the Fuchsia SDK. The current minimum supported SDK version is 20.20240412.3.1.

Fuchsia's test runner interacts with the Fuchsia emulator and is located at src/ci/docker/scripts/fuchsia-test-runner.py. First, add the following variables to your existing config-env.sh:

# TEST_TOOLCHAIN_TMP_DIR can point anywhere, but it:
#  - must be less than 108 characters, otherwise qemu can't handle the path
#  - must be consistent across calls to this file (don't use `mktemp -d` here)
export TEST_TOOLCHAIN_TMP_DIR="/tmp/rust-tmp"

# Keep existing contents of `config-env.sh` from earlier, including SDK_PATH

We can then use the script to start our test environment with:

( \
    source config-env.sh &&                                                   \
    src/ci/docker/scripts/fuchsia-test-runner.py start                        \
    --rust-build ${RUST_SRC_PATH}/build                                       \
    --sdk ${SDK_PATH}                                                         \
    --target {x86_64-unknown-fuchsia|aarch64-unknown-fuchsia}                 \
    --verbose                                                                 \
)

Where ${RUST_SRC_PATH}/build is the build-dir set in config.toml.

Once our environment is started, we can run our tests using x.py as usual. The test runner script will run the compiled tests on an emulated Fuchsia device. To run the full tests/ui test suite:

( \
    source config-env.sh &&                                                   \
    ./x.py                                                                    \
    --config config.toml                                                      \
    --stage=2                                                                 \
    test tests/ui                                                             \
    --target x86_64-unknown-fuchsia                                           \
    --run=always                                                              \
    --test-args --target-rustcflags                                           \
    --test-args -Lnative=${SDK_PATH}/arch/{x64|arm64}/sysroot/lib             \
    --test-args --target-rustcflags                                           \
    --test-args -Lnative=${SDK_PATH}/arch/{x64|arm64}/lib                     \
    --test-args --target-rustcflags                                           \
    --test-args -Clink-arg=--undefined-version                                \
    --test-args --remote-test-client                                          \
    --test-args src/ci/docker/scripts/fuchsia-test-runner.py                  \
)

By default, x.py compiles test binaries with panic=unwind. If you built your Rust toolchain with -Cpanic=abort, you need to tell x.py to compile test binaries with panic=abort as well:

    --test-args --target-rustcflags                                           \
    --test-args -Cpanic=abort                                                 \
    --test-args --target-rustcflags                                           \
    --test-args -Zpanic_abort_tests                                           \

When finished testing, the test runner can be used to stop the test environment:

src/ci/docker/scripts/fuchsia-test-runner.py stop

Debugging

zxdb

Debugging components running on a Fuchsia emulator can be done using the console-mode debugger: zxdb. We will demonstrate attaching necessary symbol paths to debug our hello-fuchsia component.

Attaching zxdb

In a separate terminal, issue the following command from our hello_fuchsia directory to launch zxdb:

In separate terminal

${SDK_PATH}/tools/${ARCH}/ffx debug connect -- \
    --symbol-path target/x86_64-unknown-fuchsia/debug

• --symbol-path gets required symbol paths, which are necessary for stepping through your program.

The "displaying source code in zxdb" section describes how you can display Rust and/or Fuchsia source code in your debugging session.

Using zxdb

Once launched, you will be presented with the window:

Connecting (use "disconnect" to cancel)...
Connected successfully.
👉 To get started, try "status" or "help".
[zxdb]

To attach to our program, we can run:

[zxdb] attach hello_fuchsia

Expected output

Waiting for process matching "hello_fuchsia".
Type "filter" to see the current filters.

Next, we can create a breakpoint at main using "b main":

[zxdb] b main

Expected output

Created Breakpoint 1 @ main

Finally, we can re-run the "hello_fuchsia" component from our original terminal:

${SDK_PATH}/tools/${ARCH}/ffx component run \
    --recreate \
    fuchsia-pkg://hello-fuchsia/hello_fuchsia_manifest#meta/hello_fuchsia.cm

Once our component is running, our zxdb window will stop execution in our main as desired:

Expected output

Breakpoint 1 now matching 1 addrs for main
🛑 on bp 1 hello_fuchsia::main() • main.rs:2
   1 fn main() {
 ▶ 2     println!("Hello Fuchsia!");
   3 }
   4
[zxdb]

zxdb has similar commands to other debuggers like gdb. To list the available commands, run "help" in the zxdb window or visit the zxdb documentation.

[zxdb] help

Expected output

Help!

  Type "help <command>" for command-specific help.

Other help topics (see "help <topic>")
...

Displaying source code in zxdb

By default, the debugger will not be able to display source code while debugging. For our user code, we displayed source code by pointing our debugger to our debug binary via the --symbol-path arg. To display library source code in the debugger, you must provide paths to the source using --build-dir. For example, to display the Rust and Fuchsia source code:

${SDK_PATH}/tools/${ARCH}/ffx debug connect -- \
    --symbol-path target/x86_64-unknown-fuchsia/debug \
    --build-dir ${RUST_SRC_PATH}/rust \
    --build-dir ${FUCHSIA_SRC_PATH}/fuchsia/out/default

• --build-dir links against source code paths, which are not strictly necessary for debugging, but is a nice-to-have for displaying source code in zxdb.

Linking to a Fuchsia checkout can help with debugging Fuchsia libraries, such as fdio.

Debugging the compiler test suite

Debugging the compiler test suite requires some special configuration:

First, we have to properly configure zxdb so it will be able to find debug symbols and source information for our test. The test runner can do this for us with:

src/ci/docker/scripts/fuchsia-test-runner.py debug                            \
    --rust-src ${RUST_SRC_PATH}                                               \
    --fuchsia-src ${FUCHSIA_SRC_PATH}                                         \
    --test ${TEST}

where ${TEST} is relative to Rust's tests directory (e.g. ui/abi/...).

This will start a zxdb session that is properly configured for the specific test being run. All three arguments are optional, so you can omit --fuchsia-src if you don't have it downloaded. Now is a good time to set any desired breakpoints, like b main.

Next, we have to tell x.py not to optimize or strip debug symbols from our test suite binaries. We can do this by passing some new arguments to rustc through our x.py invocation. The full invocation is:

( \
    source config-env.sh &&                                                   \
    ./x.py                                                                    \
    --config config.toml                                                      \
    --stage=2                                                                 \
    test tests/${TEST}                                                        \
    --target x86_64-unknown-fuchsia                                           \
    --run=always                                                              \
    --test-args --target-rustcflags                                           \
    --test-args -Lnative=${SDK_PATH}/arch/{x64|arm64}/sysroot/lib             \
    --test-args --target-rustcflags                                           \
    --test-args -Lnative=${SDK_PATH}/arch/{x64|arm64}/lib                     \
    --test-args --target-rustcflags                                           \
    --test-args -Clink-arg=--undefined-version                                \
    --test-args --target-rustcflags                                           \
    --test-args -Cdebuginfo=2                                                 \
    --test-args --target-rustcflags                                           \
    --test-args -Copt-level=0                                                 \
    --test-args --target-rustcflags                                           \
    --test-args -Cstrip=none                                                  \
    --test-args --remote-test-client                                          \
    --test-args src/ci/docker/scripts/fuchsia-test-runner.py                  \
)

If you built your Rust toolchain with panic=abort, make sure to include the previous flags so your test binaries are also compiled with panic=abort.

Upon running this command, the test suite binary will be run and zxdb will attach and load any relevant debug symbols.

aarch64-unknown-trusty and armv7-unknown-trusty

Tier: 3

Trusty is a secure Operating System that provides a Trusted Execution Environment (TEE) for Android.

Target maintainers

• Nicole LeGare (@randomPoison)
• Andrei Homescu (@ahomescu)
• Chris Wailes (chriswailes@google.com)
• As a fallback trusty-dev-team@google.com can be contacted

Requirements

These targets are cross-compiled. They have no special requirements for the host.

Support for the standard library is work-in-progress. It is expected that they will support alloc with the default allocator, and partially support std.

Trusty uses the ELF file format.

Building the target

The targets can be built by enabling them for a rustc build, for example:

[build]
build-stage = 1
target = ["aarch64-unknown-trusty", "armv7-unknown-trusty"]

Building Rust programs

There is currently no supported way to build a Trusty app with Cargo. You can follow the Trusty build instructions to build the Trusty kernel along with any Rust apps that are setup in the project.

Testing

See the Trusty build instructions for information on how to build Rust code within the main Trusty project. The main project also includes infrastructure for testing Rust applications within a QEMU emulator.

Cross-compilation toolchains and C code

See the Trusty build instructions for information on how C code is built within Trusty.

*-kmc-solid_*

Tier: 3

SOLID embedded development platform by Kyoto Microcomputer Co., Ltd.

The target names follow this format: $ARCH-kmc-solid_$KERNEL-$ABI, where $ARCH specifies the target processor architecture, $KERNEL the base kernel, and $ABI the target ABI (optional). The following targets are currently defined:

Designated Developers

• @kawadakk

Requirements

This target is cross-compiled. A platform-provided C compiler toolchain is required, though it can be substituted by GNU Arm Embedded Toolchain for the purpose of building Rust and functional binaries.

Building

The target can be built by enabling it for a rustc build.

[build]
target = ["aarch64-kmc-solid_asp3"]

Make sure aarch64-kmc-elf-gcc is included in $PATH. Alternatively, you can use GNU Arm Embedded Toolchain by adding the following to config.toml:

[target.aarch64-kmc-solid_asp3]
cc = "arm-none-eabi-gcc"

Cross-compilation

This target can be cross-compiled from any hosts.

Testing

Currently there is no support to run the rustc test suite for this target.

Building Rust programs

Building executables is not supported yet.

If rustc has support for that target and the library artifacts are available, then Rust static libraries can be built for that target:

$ rustc --target aarch64-kmc-solid_asp3 your-code.rs --crate-type staticlib
$ ls libyour_code.a

On Rust Nightly it's possible to build without the target artifacts available:

cargo build -Z build-std --target aarch64-kmc-solid_asp3

csky-unknown-linux-gnuabiv2

Tier: 3

This target supports C-SKY CPUs with abi v2 and glibc.

Reference:

• CSKY ABI Manual
• csky-linux-gnuabiv2-toolchain
• csky-linux-gnuabiv2-qemu

other links:

• https://c-sky.github.io/
• https://gitlab.com/c-sky/

Target maintainers

• @Dirreke

Requirements

Building the target

Get a C toolchain

Compiling rust for this target has been tested on x86_64 linux hosts. Other host types have not been tested, but may work, if you can find a suitable cross compilation toolchain for them.

If you don't already have a suitable toolchain, you can download from here, and unpack it into a directory.

Configure rust

The target can be built by enabling it for a rustc build, by placing the following in config.toml:

[build]
target = ["x86_64-unknown-linux-gnu", "csky-unknown-linux-gnuabiv2", "csky-unknown-linux-gnuabiv2hf"]
stage = 2

[target.csky-unknown-linux-gnuabiv2]
# ADJUST THIS PATH TO POINT AT YOUR TOOLCHAIN
cc = "${TOOLCHAIN_PATH}/bin/csky-linux-gnuabiv2-gcc"

[target.csky-unknown-linux-gnuabiv2hf]
# ADJUST THIS PATH TO POINT AT YOUR TOOLCHAIN
cc = "${TOOLCHAIN_PATH}/bin/csky-linux-gnuabiv2-gcc"

Build

# in rust dir
./x.py build --stage 2

Building and Running Rust programs

To test cross-compiled binaries on a x86_64 system, you can use the qemu-cskyv2. This avoids having a full emulated ARM system by doing dynamic binary translation and dynamic system call translation. It lets you run CSKY programs directly on your x86_64 kernel. It's very convenient!

To use:

• Install qemu-cskyv2 (If you don't already have a qemu, you can download from here, and unpack it into a directory.)
• Link your built toolchain via:
  • rustup toolchain link stage2 ${RUST}/build/x86_64-unknown-linux-gnu/stage2
• Create a test program

cargo new hello_world
cd hello_world

• Build and run

CARGO_TARGET_CSKY_UNKNOWN_LINUX_GNUABIV2_RUNNER=${QEMU_PATH}/bin/qemu-cskyv2 -L ${TOOLCHAIN_PATH}/csky-linux-gnuabiv2/libc \
CARGO_TARGET_CSKY_UNKNOWN_LINUX_GNUABIV2_LINKER=${TOOLCHAIN_PATH}/bin/csky-linux-gnuabiv2-gcc \
RUSTFLAGS="-C target-feature=+crt-static" \
cargo +stage2 run --target csky-unknown-linux-gnuabiv2

Attention: The dynamic-linked program may nor be run by qemu-cskyv2 but can be run on the target.

hexagon-unknown-linux-musl

Tier: 3

Target for cross-compiling Linux user-mode applications targeting the Hexagon DSP architecture.

Target maintainers

• Brian Cain, bcain@quicinc.com

Requirements

The target is cross-compiled. This target supports std. By default, code generated with this target should run on Hexagon DSP hardware.

• -Ctarget-cpu=hexagonv73 adds support for instructions defined up to Hexagon V73.

Binaries can be run using QEMU user emulation. On Debian-based systems, it should be sufficient to install the package qemu-user-static to be able to run simple static binaries:

# apt install qemu-user-static
# qemu-hexagon-static ./hello

In order to build linux programs with Rust, you will require a linker capable of targeting hexagon. You can use clang/lld from the hexagon toolchain using exclusively public open source repos.

Also included in that toolchain is the C library that can be used when creating dynamically linked executables.

# /opt/clang+llvm-18.1.0-cross-hexagon-unknown-linux-musl/x86_64-linux-gnu/bin/qemu-hexagon -L /opt/clang+llvm-18.1.0-cross-hexagon-unknown-linux-musl/x86_64-linux-gnu/target/hexagon-unknown-linux-musl/usr/ ./hello

Building the target

Because it is Tier 3, rust does not yet ship pre-compiled artifacts for this target.

Therefore, you can build Rust with support for the target by adding it to the target list in config.toml, a sample configuration is shown below.

[build]
target = ["hexagon-unknown-linux-musl"]

[target.hexagon-unknown-linux-musl]

cc = "hexagon-unknown-linux-musl-clang"
cxx = "hexagon-unknown-linux-musl-clang++"
linker = "hexagon-unknown-linux-musl-clang"
ar = "hexagon-unknown-linux-musl-ar"
ranlib = "hexagon-unknown-linux-musl-ranlib"
musl-root = "/opt/clang+llvm-18.1.0-cross-hexagon-unknown-linux-musl/x86_64-linux-gnu/target/hexagon-unknown-linux-musl/usr"
llvm-libunwind = 'in-tree'
qemu-rootfs = "/opt/clang+llvm-18.1.0-cross-hexagon-unknown-linux-musl/x86_64-linux-gnu/target/hexagon-unknown-linux-musl/usr"

Testing

Currently there is no support to run the rustc test suite for this target.

Building Rust programs

Download and install the hexagon open source toolchain from https://github.com/quic/toolchain_for_hexagon/releases

The following .cargo/config is needed inside any project directory to build for the Hexagon Linux target:

[build]
target = "hexagon-unknown-linux-musl"

[target.hexagon-unknown-linux-musl]
linker = "hexagon-unknown-linux-musl-clang"
ar = "hexagon-unknown-linux-musl-ar"
runner = "qemu-hexagon -L /opt/clang+llvm-18.1.0-cross-hexagon-unknown-linux-musl/x86_64-linux-gnu/target/hexagon-unknown-linux-musl/usr"

Edit the "runner" in .cargo/config to point to the path to your toolchain's C library.

...
runner = "qemu-hexagon -L /path/to/my/inst/clang+llvm-18.1.0-cross-hexagon-unknown-linux-musl/x86_64-linux-gnu/target/hexagon-unknown-linux-musl/usr"
...

Build/run your rust program with qemu-hexagon in your PATH:

export PATH=/path/to/my/inst/clang+llvm-18.1.0-cross-hexagon-unknown-linux-musl/x86_64-linux-gnu/bin/:$PATH
cargo run -Zbuild-std -Zbuild-std-features=llvm-libunwind

hexagon-unknown-none-elf

Tier: 3

Rust for baremetal Hexagon DSPs.

Target maintainers

• Brian Cain, bcain@quicinc.com

Requirements

This target is cross-compiled. There is no support for std. There is no default allocator, but it's possible to use alloc by supplying an allocator.

By default, code generated with this target should run on Hexagon DSP hardware.

• -Ctarget-cpu=hexagonv73 adds support for instructions defined up to Hexagon V73.

Functions marked extern "C" use the Hexagon architecture calling convention.

This target generates PIC ELF binaries.

Building the target

You can build Rust with support for the target by adding it to the target list in config.toml:

[build]
build-stage = 1
host = ["<target for your host>"]
target = ["<target for your host>", "hexagon-unknown-none-elf"]

[target.hexagon-unknown-none-elf]

cc = "hexagon-unknown-none-elf-clang"
cxx = "hexagon-unknown-none-elf-clang++"
linker = "hexagon-unknown-none-elf-clang"
ranlib = "hexagon-unknown-none-elf-ranlib"
ar = "hexagon-unknown-none-elf-ar"
llvm-libunwind = 'in-tree'

Replace <target for your host> with x86_64-unknown-linux-gnu or whatever else is appropriate for your host machine.

Building Rust programs

Rust does not yet ship pre-compiled artifacts for this target. To compile for this target, you will either need to build Rust with the target enabled (see "Building the target" above), or build your own copy of core by using build-std or similar.

Testing

Since hexagon-unknown-none-elf supports a variety of different environments and does not support std, this target does not support running the Rust test suite.

Cross-compilation toolchains and C code

This target has been tested using qemu-system-hexagon.

A common use case for hexagon-unknown-none-elf is building libraries that link against C code and can be used in emulation or on a device with a Hexagon DSP.

The Hexagon SDK has libraries which are useful to link against when running on a device.

Standalone OS

The script below will build an executable against "hexagon standalone OS" which is suitable for emulation or bare-metal on-device testing.

First, run cargo new --bin demo1_hexagon then add the source below as src/main.rs. This program demonstrates the console output via semihosting.

#![no_std]
#![no_main]

extern "C" {
    fn putchar(ch: i32);
    fn _exit(code: i32) -> !;
}

#[no_mangle]
extern "C" fn main() -> i32 {
    let message = "Hello, this is Rust!";
    for b in message.bytes() {
        unsafe {
            putchar(b as i32);
        }
    }
    0
}

#[panic_handler]
fn panic(_panic: &core::panic::PanicInfo) -> ! {
    unsafe {
        _exit(1);
    }
}

Next, save the script below as build.sh and edit it to suit your environment.

• hex_toolchain below refers to the hexagon toolchain using exclusively public open source repos.
• cc below refers to clang. You can use clang from your distribution, as long as it's at least clang-17. Or you can use hexagon-unknown-none-elf-clang from one of the hexagon open source toolchain releases.

# Hexagon SDK, required for target libraries:
hex_sdk_root=/local/mnt/workspace/Qualcomm/Hexagon_SDK/5.3.0.0
hex_sdk_toolchain=${hex_sdk_root}/tools/HEXAGON_Tools/8.6.06

sdk_libs=${hex_sdk_toolchain}/Tools/target/hexagon/lib
q6_arch=v65
g0_lib_path=${sdk_libs}/${q6_arch}/G0
pic_lib_path=${sdk_libs}/${q6_arch}/G0/pic

build_cfg=release
cargo build --target=hexagon-unknown-none-elf -Zbuild-std --release

# Builds an executable against "hexagon standalone OS" suitable for emulation:
${cc} --target=hexagon-unknown-none-elf -o testit \
    -fuse-ld=lld \
    -m${q6_arch} \
    -nodefaultlibs \
    -nostartfiles \
    ${g0_lib_path}/crt0_standalone.o \
    ${g0_lib_path}/crt0.o \
    ${g0_lib_path}/init.o \
    -L${sdk_libs}/${q6_arch}/ \
    -L${sdk_libs}/ \
    wrap.c \
    target/hexagon-unknown-none-elf/${build_cfg}/libdemo1_hexagon.rlib \
    target/hexagon-unknown-none-elf/${build_cfg}/deps/libcore-*.rlib \
    target/hexagon-unknown-none-elf/${build_cfg}/deps/libcompiler_builtins-*.rlib \
    -Wl,--start-group \
    -Wl,--defsym,_SDA_BASE_=0,--defsym,__sbss_start=0,--defsym,__sbss_end=0 \
    ${g0_lib_path}/libstandalone.a \
    ${g0_lib_path}/libc.a \
    -lgcc \
    -lc_eh \
    -Wl,--end-group \
    ${g0_lib_path}/fini.o \

${hex_toolchain}/x86_64-linux-gnu/bin/qemu-system-hexagon -monitor none -display none -kernel ./testit

QuRT OS

First, run cargo new --lib demo2_hexagon then add the source below as src/lib.rs. This program demonstrates inline assembly and console output via semihosting.

#![no_std]
#![no_main]
#![feature(lang_items)]
#![feature(asm_experimental_arch)]

use core::arch::asm;

extern "C" {
    fn putchar(ch: i32);
    fn _exit(code: i32) -> !;
}

fn hexagon_specific() {
    let mut buffer = [0_u8; 128];

    unsafe {
        let mut x = &buffer;
        asm!(
                "{{\n\t",
                "  v0=vmem({addr}+#0)\n\t",
                "  {tmp} = and({tmp}, #1)\n\t",
                "}}\n\t",
                addr = in(reg) x,
                tmp = out(reg) _,
            );
    }
}

#[no_mangle]
extern "C" fn hello() -> i32 {
    let message = "Hello, this is Rust!\n";
    for b in message.bytes() {
        unsafe {
            putchar(b as i32);
        }
    }
    hexagon_specific();
    0
}

#[panic_handler]
fn panic(_panic: &core::panic::PanicInfo) -> ! {
    unsafe {
        _exit(1);
    }
}

#[lang = "eh_personality"]
fn rust_eh_personality() {}

Next, create a C program as an entry point, save the content below as wrap.c:

int hello();

int main() {
    hello();
}

Then, save the script below as build.sh and edit it to suit your environment. The script below will build a shared object against the QuRT RTOS which is suitable for emulation or on-device testing when loaded via the fastrpc-shell.

# Hexagon SDK, required for target libraries:
hex_sdk_root=/local/mnt/workspace/Qualcomm/Hexagon_SDK/5.3.0.0
hex_sdk_toolchain=${hex_sdk_root}/tools/HEXAGON_Tools/8.6.06

sdk_libs=${hex_sdk_toolchain}/Tools/target/hexagon/lib
q6_arch=v65
g0_lib_path=${sdk_libs}/${q6_arch}/G0
pic_lib_path=${sdk_libs}/${q6_arch}/G0/pic
runelf=${hex_sdk_root}/rtos/qurt/computev65/sdksim_bin/runelf.pbn
rmohs=${hex_sdk_root}/libs/run_main_on_hexagon/ship/hexagon_toolv86_${q6_arch}/run_main_on_hexagon_sim

# Builds a library suitable for loading into "run_main_on_hexagon_sim" for
# emulation or frpc shell on real target:
${cc} --target=hexagon-unknown-none-elf -o testit.so \
    -fuse-ld=lld \
    -fPIC -shared \
    -nostdlib \
    -Wl,-Bsymbolic \
      -Wl,--wrap=malloc \
      -Wl,--wrap=calloc \
      -Wl,--wrap=free \
      -Wl,--wrap=realloc \
      -Wl,--wrap=memalign \
    -m${q6_arch} \
    wrap.c \
    target/hexagon-unknown-none-elf/${build_cfg}/libdemo2_hexagon.rlib \
    target/hexagon-unknown-none-elf/${build_cfg}/deps/libcore-*.rlib \
    target/hexagon-unknown-none-elf/${build_cfg}/deps/libcompiler_builtins-*.rlib \
    -Wl,-soname=testit \
    ${pic_lib_path}/libc.so

# -Bsymbolic above for memory alloc funcs is necessary to access the heap on
# target, but otherwise not required.

# multi-stage loader: runelf => run_main_on_hexagon_sim => testit.so{`main`}
${hex_toolchain}/x86_64-linux-gnu/bin/qemu-system-hexagon \
    -monitor none \
    -display none \
    -kernel ${runelf} \
    -append "${rmohs} -- ./testit.so"

aarch64-unknown-illumos and x86_64-unknown-illumos

Tier: 2/3

illumos, is a Unix operating system which provides next-generation features for downstream distributions, including advanced system debugging, next generation filesystem, networking, and virtualization options.

Target maintainers

• Joshua M. Clulow (@jclulow)
• Patrick Mooney (@pfmooney)

Requirements

The target supports host tools.

The illumos target supports std and uses the standard ELF file format.

x86_64-unknown-illumos is a tier 2 target with host tools. aarch64-unknown-illumos is a tier 3 target.

Building the target

These targets can be built by adding aarch64-unknown-illumos and x86_64-unknown-illumos as targets in the rustc list.

Building Rust programs

Rust ships pre-compiled artifacts for the x86_64-unknown-illumos target. Rust does not ship pre-compiled artifacts for aarch64-unknown-illumos, it requires building the target either as shown above or using -Zbuild-std.

Testing

Tests can be run in the same way as a regular binary.

Cross-compilation toolchains and C code

The target supports C code.

The illumos project makes available prebuilt sysroot artefacts which can be used for cross compilation. The official Rust binaries are cross-compiled using these artefacts.

loongarch*-unknown-linux-*

Tier: 2 (with Host Tools)

LoongArch Linux targets. LoongArch is a RISC ISA developed by Loongson Technology Corporation Limited.

These support both native and cross builds, and have full support for std.

Reference material:

• LoongArch ISA manuals
• Application Binary Interface for the LoongArch™ Architecture

Target maintainers

• WANG Rui wangrui@loongson.cn
• ZHAI Xiang zhaixiang@loongson.cn
• ZHAI Xiaojuan zhaixiaojuan@loongson.cn
• WANG Xuerui git@xen0n.name