From de792eb0303de6ed2fbe84926b2b0772765b825c Mon Sep 17 00:00:00 2001 From: Jubilee Young Date: Mon, 16 Jun 2025 21:00:21 -0700 Subject: [PATCH 1/2] compiler: Redescribe rustc_target::spec more accurately --- compiler/rustc_target/src/spec/mod.rs | 26 ++++++++++++++++++-------- 1 file changed, 18 insertions(+), 8 deletions(-) diff --git a/compiler/rustc_target/src/spec/mod.rs b/compiler/rustc_target/src/spec/mod.rs index 010355abd7817..8166c9ef5d689 100644 --- a/compiler/rustc_target/src/spec/mod.rs +++ b/compiler/rustc_target/src/spec/mod.rs @@ -25,14 +25,24 @@ //! //! # Defining a new target //! -//! Targets are defined using [JSON](https://json.org/). 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. +//! 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. +//! +//! [JSON]: https://json.org use std::borrow::Cow; use std::collections::BTreeMap; From 679a2e3a5b8e57264170403ac86e7eba00035c2d Mon Sep 17 00:00:00 2001 From: Jubilee Young Date: Mon, 16 Jun 2025 21:24:53 -0700 Subject: [PATCH 2/2] compiler: Redescribe rustc_target search algo more accurately --- compiler/rustc_target/src/spec/mod.rs | 21 +++++++-------------- 1 file changed, 7 insertions(+), 14 deletions(-) diff --git a/compiler/rustc_target/src/spec/mod.rs b/compiler/rustc_target/src/spec/mod.rs index 8166c9ef5d689..7a49f0040722c 100644 --- a/compiler/rustc_target/src/spec/mod.rs +++ b/compiler/rustc_target/src/spec/mod.rs @@ -6,22 +6,15 @@ //! to a new platform, and allows for an unprecedented level of control over how //! the compiler works. //! -//! # Using custom targets +//! # Using targets and target.json //! -//! 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. +//! 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" //! -//! Projects defining their own targets should use -//! `--target=path/to/my-awesome-platform.json` instead of adding to -//! `RUST_TARGET_PATH`. +//! Code will then be compiled using the first discovered target spec. //! //! # Defining a new target //!