rucc_tuple/
lib.rs

1//! The target tuple for rucc.
2//!
3//! A target is not three strings. It is the set of facts that change the bytes the compiler
4//! emits, and there are ten of them: the architecture, the baseline within it, the byte order,
5//! the data model, the OS, the OS version, the environment, the environment version, the float
6//! ABI, and the object format. `spec/cross-compile/03-target-model.md` argues for each one, and the argument
7//! is always the same: if the fact changes how a function is called or how a struct is laid out,
8//! then two objects that disagree about it do not link, so it is part of the target's identity
9//! and not a flag.
10//!
11//! That identity property is what the rest of the cross compilation work is built on. The
12//! sysroot cache in `spec/cross-compile/13-distribution.md` is keyed on a tuple, the stub libraries in
13//! `spec/cross-compile/09-libc-stubs.md` are generated per tuple, and the report that decides a target's tier
14//! is indexed by tuple. All three break if two spellings of one target produce two keys, or if
15//! one spelling produces two different sets of bytes.
16//!
17//! # What this replaces
18//!
19//! The compiler currently has a three field `Triple` with the architecture, the OS and the
20//! environment, and two functions on `Arch` that answer the pointer width and the byte order.
21//! Both functions are wrong for targets in `spec/cross-compile/04-target-matrix.md`: a 64-bit architecture on
22//! Windows has a 32-bit `long`, `x86_64-linux-gnux32` has 32-bit pointers, and five of the ten
23//! architectures here have a big endian mode. The old `FromStr` also had a catch-all arm that
24//! discarded any component it did not recognize, so `x86_64-linux-gnu.2.28` parsed as
25//! `x86_64-linux-gnu` and the pinned glibc version vanished without a word.
26//!
27//! # Example
28//!
29//! ```
30//! use rucc_tuple::{DataModel, ObjectFormat, TargetTuple};
31//!
32//! let target: TargetTuple = "x86_64-pc-windows-msvc".parse().unwrap();
33//! assert_eq!(target.data_model(), DataModel::Llp64);
34//! assert_eq!(target.data_model().long_width(), 32);
35//! assert_eq!(target.pointer_width(), 64);
36//! assert_eq!(target.object_format(), ObjectFormat::Coff);
37//! assert_eq!(target.to_canonical_string(), "x86_64-windows-msvc");
38//! assert_eq!(target.to_llvm_string(), "x86_64-pc-windows-msvc");
39//! ```
40
41#![doc(html_root_url = "https://docs.rs/rucc-tuple/0.9.5")]
42// Every public item here is read by somebody bringing up a target who has the psABI document
43// open beside it, so an undocumented one is a question they have to answer by reading the body.
44#![deny(missing_docs)]
45
46mod abi;
47mod arch;
48mod error;
49mod os;
50mod parse;
51mod table;
52mod tuple;
53
54pub use abi::{Abi, ObjectFormat};
55pub use arch::{Arch, DataModel, Endian, SubArch};
56pub use error::Error;
57pub use os::{Env, Os, Version};
58pub use table::{
59    Host, TARGETS, TargetEntry, Tier, counts_by_planned_tier, lookup, planned_working_count,
60};
61pub use tuple::{TargetTuple, TupleBuilder};
rucc_tuple/lib.rs

rucc_tuple/
lib.rs
