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 targets and target.json
Invoking “rustc –target=${TUPLE}” will result in rustc initiating the Target::search by
- checking if “$TUPLE” is a complete path to a json (ending with “.json”) and loading if so
- checking builtin targets for “${TUPLE}”
- checking directories in “${RUST_TARGET_PATH}” for “${TUPLE}.json”
- checking for “${RUSTC_SYSROOT}/lib/rustlib/${TUPLE}/target.json”
Code will then be compiled using the first discovered target spec.
§Defining a new target
Targets are defined using a struct which additionally has serialization to and from JSON.
The Target struct in this module loosely corresponds with the format the JSON takes.
We usually try to make the fields equivalent but we have given up on a 1:1 correspondence
between the JSON and the actual structure itself.
Some fields are required in every target spec, and they should be embedded in Target directly. Optional keys are in TargetOptions, but Target derefs to it, for no practical difference. Most notable is the “data-layout” field which specifies Rust’s notion of sizes and alignments for several key types, such as f64, pointers, and so on.
At one point we felt -C options should override the target’s settings, like in C compilers,
but that was an essentially-unmarked route for making code incorrect and Rust unsound.
Confronted with programmers who prefer a compiler with a good UX instead of a lethal weapon,
we have almost-entirely recanted that notion, though we hope “target modifiers” will offer
a way to have a decent UX yet still extend the necessary compiler controls, without
requiring a new target spec for each and every single possible target micro-variant.
Modules§
- abi_map 🔒
- apple
- 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§
- AbiMap
- Mapping for ExternAbi to CanonAbi according to a Target
- 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§
- AbiMapping
- result from trying to map an ABI
- 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
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 🔒