Expand description
Flexible target specification.
Rust targets a wide variety of usecases, and in the interest of flexibility, allows new target tuples to be defined in configuration files. Most users will not need to care about these, but this is invaluable when porting Rust to a new platform, and allows for an unprecedented level of control over how the compiler works.
§Using custom targets
A target tuple, as passed via rustc --target=TUPLE, will first be
compared against the list of built-in targets. This is to ease distributing
rustc (no need for configuration files) and also to hold these built-in
targets as immutable and sacred. If TUPLE is not one of the built-in
targets, rustc will check if a file named TUPLE exists. If it does, it
will be loaded as the target configuration. If the file does not exist,
rustc will search each directory in the environment variable
RUST_TARGET_PATH for a file named TUPLE.json. The first one found will
be loaded. If no file is found in any of those directories, a fatal error
will be given.
Projects defining their own targets should use
--target=path/to/my-awesome-platform.json instead of adding to
RUST_TARGET_PATH.
§Defining a new target
Targets are defined using JSON. The Target struct in
this module defines the format the JSON file should take, though each
underscore in the field names should be replaced with a hyphen (-) in the
JSON file. Some fields are required in every target specification, such as
llvm-target, target-endian, target-pointer-width, data-layout,
arch, and os. In general, options passed to rustc with -C override
the target’s settings, though target-feature and link-args will add
to the list specified by the target, rather than replace.
Modules§
- base 🔒
- crt_
objects - Object files providing support for basic runtime facilities and added to the produced binaries at the start and at the end of linking.
- json 🔒
- targets 🔒
Macros§
- cvs 🔒
- Cow-Vec-Str: Cow<’static, [Cow<’static, str>]>
- linker_
flavor_ 🔒cli_ impls - supported_
targets 🔒
Structs§
- Link
Self Contained Components - The
-C link-self-containedcomponents that can individually be enabled or disabled. - Linker
Features - The
-Z linker-featurescomponents that can individually be enabled or disabled. - Sanitizer
Set - Target
- Everything
rustcknows about how to compile for a specific target. - Target
Metadata - Metadata about a target like the description or tier. Part of #120745. All fields are optional for now, but intended to be required in the future.
- Target
Options - Optional aspects of a target specification.
- Target
Warnings - Warnings encountered when parsing the target
json. - X86Abi
- x86 (32-bit) abi options.
Enums§
- Binary
Format - Cc
- Linker is called through a C/C++ compiler.
- Code
Model - Debuginfo
Kind - Which kind of debuginfo does the target use?
- Float
Abi - The float ABI setting to be configured in the LLVM target machine.
- Frame
Pointer - Link
Output Kind - Everything is flattened to a single enum to make the json encoding/decoding less annoying.
- Link
Self Contained Default - The different
-Clink-self-containedoptions that can be specified in a target spec: - Linker
Flavor - All linkers have some kinds of command line interfaces and rustc needs to know which commands to use with each of them. So we cluster all such interfaces into a (somewhat arbitrary) number of classes that we call “linker flavors”.
- Linker
Flavor Cli - Linker flavors available externally through command line (
-Clinker-flavor) or json target specifications. This set has accumulated historically, and contains both (stable and unstable) legacy values, as well as modern ones matching the internal linker flavors (LinkerFlavor). - Lld
- Linker is LLD.
- LldFlavor
- Merge
Functions - OnBroken
Pipe - Panic
Strategy - Reloc
Model - Relro
Level - Rustc
Abi - The Rustc-specific variant of the ABI used for this target.
- Small
Data Threshold Support - Split
Debuginfo - Stack
Probe Type - Stack
Protector - Controls use of stack canaries.
- Symbol
Visibility - Target
Kind 🔒 - For the
Target::check_consistencyfunction, determines whether the given target is a builtin or a JSON target. - Target
Tuple - Either a target tuple string or a path to a JSON file.
- TlsModel
- WasmC
Abi - Which C ABI to use for
wasm32-unknown-unknown.
Statics§
- TARGETS
- List of supported targets
Traits§
Functions§
- add_
link_ 🔒args - add_
link_ 🔒args_ iter - Add arguments for the given flavor and also for its “twin” flavors that have a compatible command line interface.
- ef_
avr_ arch - Resolve the value of the EF_AVR_ARCH field for AVR ELF files, given the name of the target CPU / MCU.
- load_
all_ 🔒builtins - load_
builtin 🔒