1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
//! Where a target's headers and link inputs live, which directories are searched for them, and in
//! what order they reach the linker.
//!
//! Design: `spec/cross-compile/08-sysroots.md`, and section 8.5 for the rule this crate exists to
//! enforce.
//!
//! # The claim this crate is responsible for
//!
//! `spec/cross-compile/02-the-goal.md` claim 5 is byte identical output from different hosts for
//! the same target. It holds only because the search path rules make the libc header directory a
//! function of the target rather than of the machine, and that function is here.
//!
//! So every answer in this crate is derived from a [`TargetTuple`] and from paths the caller
//! supplies. Nothing reads an environment variable, nothing looks at `std::env::consts`, and
//! nothing touches the filesystem. A host directory can only enter through
//! [`Options::host_include`], which [`include_paths`] uses exactly once and only when the target
//! is the host, and that is checkable by reading one function.
//!
//! # What is in here
//!
//! [`Sysroot`] is the directory layout for one target: where its headers go, where its link inputs
//! go, and where the record of what they are goes. Its root is a function of a cache directory and
//! the tuple, which is what makes the tuple a cache key.
//!
//! [`include_paths`] is section 8.5 as an ordered list, with each entry saying which of the four
//! steps put it there. [`LinkLine`] is the start files, the libraries and the end files for a musl
//! link, in the order a linker needs them.
//!
//! [`Manifest`] is what a produced sysroot carries: every input with where it came from, its hash
//! and its licence. Two sysroots for the same target built on two hosts have the same manifest, and
//! comparing manifests is how that gets checked without comparing several thousand files.
//!
//! # What is not in here
//!
//! Nothing fetches. Downloading musl, verifying it and unpacking it is
//! `spec/cross-compile/13-distribution.md`, and it needs a cache, a provenance record and a network
//! policy that this crate deliberately has no opinion about. What this crate settles is where the
//! result goes and how it is searched, which is the part that has to be decided before anything is
//! worth downloading.
//!
//! ```
//! use rucc_sysroot::{Sysroot, LinkLine, LinkMode};
//! use rucc_tuple::TargetTuple;
//! use std::path::Path;
//!
//! let target: TargetTuple = "aarch64-linux-musl".parse().unwrap();
//! let sysroot = Sysroot::in_cache(Path::new("/cache"), target);
//!
//! // The cache key is the canonical spelling, so two hosts asking for the same target ask for
//! // the same directory.
//! assert_eq!(sysroot.cache_key(), "aarch64-linux-musl");
//! assert_eq!(sysroot.root(), Path::new("/cache/sysroots/aarch64-linux-musl"));
//!
//! // A static link needs three start files, and `crtn.o` goes after the libraries rather than
//! // with the other two.
//! let line = LinkLine::musl(&sysroot, LinkMode::Static);
//! assert_eq!(line.start.last().unwrap().file_name().unwrap(), "crti.o");
//! assert_eq!(line.end.first().unwrap().file_name().unwrap(), "crtn.o");
//! assert!(line.flags.iter().any(|flag| flag == "-static"));
//! ```
// Every public item here is read by somebody bringing up a target, and an undocumented one is a
// question they have to answer by reading the body.
pub use Sysroot;
pub use ;
pub use ;
pub use ;
pub use TargetTuple;