Module spec

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

• abi
• 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.
• targets 🔒

Macros

• cvs 🔒
  Cow-Vec-Str: Cow<’static, [Cow<’static, str>]>
• linker_flavor_cli_impls 🔒
• supported_targets 🔒

Structs

• LinkSelfContainedComponents
  The -C link-self-contained components that can individually be enabled or disabled.
• LinkerFeatures
  The -Z linker-features components that can individually be enabled or disabled.
• SanitizerSet
• Target
  Everything rustc knows about how to compile for a specific target.
• TargetMetadata
  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.
• TargetOptions
  Optional aspects of a target specification.
• TargetWarnings
  Warnings encountered when parsing the target json.
• X86Abi
  x86 (32-bit) abi options.

Enums

• Cc
  Linker is called through a C/C++ compiler.
• CodeModel
• DebuginfoKind
  Which kind of debuginfo does the target use?
• FramePointer
• LinkOutputKind
  Everything is flattened to a single enum to make the json encoding/decoding less annoying.
• LinkSelfContainedDefault
  The different -Clink-self-contained options that can be specified in a target spec:
• LinkerFlavor
  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”.
• LinkerFlavorCli
  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
• MergeFunctions
• OnBrokenPipe
• PanicStrategy
• RelocModel
• RelroLevel
• SmallDataThresholdSupport
• SplitDebuginfo
• StackProbeType
• StackProtector
  Controls use of stack canaries.
• SymbolVisibility
• TargetTuple
  Either a target tuple string or a path to a JSON file.
• TlsModel
• WasmCAbi
  Which C ABI to use for wasm32-unknown-unknown.

Constants

• TARGETS
  List of supported targets

Traits

• HasTargetSpec
• HasWasmCAbiOpt
• HasX86AbiOpt

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_builtin 🔒

Type Aliases

• LinkArgs
• LinkArgsCli
• StaticCow 🔒