Noratrieb/target-tier-docs-experiment
1
0
Fork 0
mirror of https://github.com/Noratrieb/target-tier-docs-experiment.git synced 2026-01-14 16:35:09 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

rewrite it all

Browse source
This commit is contained in:
nora 2024-02-07 18:38:36 +01:00
parent 761818fda2
commit b90a97face
6 changed files with 321 additions and 129 deletions
Download patch file Download diff file Expand all files Collapse all files

90
Cargo.lock generated
View file

@ -39,6 +39,16 @@ version = "1.0.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5443807d6dff69373d433ab9ef5378ad8df50ca6298caf15de6e52e24aaf54d5"
[[package]]
name = "eyre"
version = "0.6.12"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7cd915d99f24784cdc19fd37ef22b97e3ff0ae756c7e492e9fbfe897d61e2aec"
dependencies = [
"indenter",
"once_cell",
]
[[package]]
name = "glob-match"
version = "0.2.1"
@ -51,6 +61,12 @@ version = "0.14.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "290f1a1d9242c78d09ce40a5e87e7554ee637af1351968159f4952f028f75604"
[[package]]
name = "indenter"
version = "0.3.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ce23b50ad8242c51a442f3ff322d56b02f08852c77e4c0b4d3fd684abc89c683"
[[package]]
name = "indexmap"
version = "2.2.2"
@ -62,10 +78,16 @@ dependencies = [
]
[[package]]
name = "memchr"
version = "2.7.1"
name = "itoa"
version = "1.0.10"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "523dc4f511e55ab87b694dc30d0f820d60906ef06413f93d4d7a1385599cc149"
checksum = "b1a46d1a171d865aa5f83f92695765caa047a9b4cbae2cbf37dbd613a793fd4c"
[[package]]
name = "once_cell"
version = "1.19.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3fdb12b2476b595f9358c5161aa467c2438859caa136dec86c26fdd2efe17b92"
[[package]]
name = "proc-macro2"
@ -105,6 +127,12 @@ dependencies = [
"crossbeam-utils",
]
[[package]]
name = "ryu"
version = "1.0.16"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f98d2aa92eebf49b69786be48e4477826b256916e84a57ff2a4f21923b48eb4c"
[[package]]
name = "serde"
version = "1.0.196"
@ -126,12 +154,16 @@ dependencies = [
]
[[package]]
name = "serde_spanned"
version = "0.6.5"
name = "serde_yaml"
version = "0.9.31"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "eb3622f419d1296904700073ea6cc23ad690adbd66f13ea683df73298736f0c1"
checksum = "adf8a49373e98a4c5f0ceb5d05aa7c648d75f63774981ed95b7c7443bbd50c6e"
dependencies = [
"indexmap",
"itoa",
"ryu",
"serde",
"unsafe-libyaml",
]
[[package]]
@ -149,44 +181,11 @@ dependencies = [
name = "target-docs"
version = "0.1.0"
dependencies = [
"eyre",
"glob-match",
"rayon",
"serde",
"toml",
]
[[package]]
name = "toml"
version = "0.8.10"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9a9aad4a3066010876e8dcf5a8a06e70a558751117a145c6ce2b82c2e2054290"
dependencies = [
"serde",
"serde_spanned",
"toml_datetime",
"toml_edit",
]
[[package]]
name = "toml_datetime"
version = "0.6.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3550f4e9685620ac18a50ed434eb3aec30db8ba93b0287467bca5826ea25baf1"
dependencies = [
"serde",
]
[[package]]
name = "toml_edit"
version = "0.22.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0c9ffdf896f8daaabf9b66ba8e77ea1ed5ed0f72821b398aba62352e95062951"
dependencies = [
"indexmap",
"serde",
"serde_spanned",
"toml_datetime",
"winnow",
"serde_yaml",
]
[[package]]
@ -196,10 +195,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3354b9ac3fae1ff6755cb6db53683adb661634f67557942dea4facebec0fee4b"
[[package]]
name = "winnow"
version = "0.5.37"
name = "unsafe-libyaml"
version = "0.2.10"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a7cad8365489051ae9f054164e459304af2e7e9bb407c958076c8bf4aef52da5"
dependencies = [
"memchr",
]
checksum = "ab4c90930b95a82d00dc9e9ac071b4991924390d46cbd0dfe566148667605e4b"

3
Cargo.toml
View file

@ -6,7 +6,8 @@ edition = "2021"
# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
[dependencies]
eyre = "0.6.12"
glob-match = "0.2.1"
rayon = "1.8.1"
serde = { version = "1.0.196", features = ["derive"] }
toml = "0.8.10"
serde_yaml = "0.9.31"

123
src/main.rs
View file

@ -1,23 +1,30 @@
mod parse;
use std::{
io,
path::{Path, PathBuf},
process::Command,
};
use parse::ParsedTargetInfoFile;
use rayon::iter::{IntoParallelRefIterator, ParallelIterator};
/// Information about a target obtained from `target_info.toml``.
struct TargetDocs {
name: String,
maintainers: Vec<String>,
requirements: Option<String>,
testing: Option<String>,
building_the_target: Option<String>,
cross_compilation: Option<String>,
building_rust_programs: Option<String>,
tier: u8,
sections: Vec<(String, String)>,
tier: String,
}
const SECTIONS: &[&str] = &[
"Requirements",
"Testing",
"Building",
"Cross compilation",
"Building Rust programs",
];
fn main() {
let rustc =
PathBuf::from(std::env::var("RUSTC").expect("must pass RUSTC env var pointing to rustc"));
@ -31,7 +38,11 @@ fn main() {
e @ _ => e.unwrap(),
}
let mut info_patterns = load_target_info_patterns();
let mut info_patterns = parse::load_target_infos(Path::new("target_info"))
.unwrap()
.into_iter()
.map(|info| TargetPatternEntry { info, used: false })
.collect::<Vec<_>>();
eprintln!("Collecting rustc information");
let rustc_infos = targets
@ -92,19 +103,18 @@ fn render_target_md(target: &TargetDocs, rustc_info: &RustcTargetInfo) -> String
doc.push_str(&maintainers_str);
let mut section = |value: &Option<String>, name| {
for section_name in SECTIONS {
let value = target
.sections
.iter()
.find(|(name, _)| name == section_name);
let section_str = match value {
Some(value) => format!("## {name}\n{value}\n"),
None => format!("## {name}\nUnknown.\n"),
Some((name, value)) => format!("## {name}\n{value}\n"),
None => format!("## {section_name}\nUnknown.\n"),
};
doc.push_str(&section_str)
};
section(&target.requirements, "Requirements");
section(&target.testing, "Testing");
section(&target.building_the_target, "Building");
section(&target.cross_compilation, "Cross Compilation");
section(&target.building_rust_programs, "Building Rust Programs");
}
let cfg_text = rustc_info
.target_cfgs
@ -114,7 +124,8 @@ fn render_target_md(target: &TargetDocs, rustc_info: &RustcTargetInfo) -> String
.join("\n");
let cfg_text =
format!("This target defines the following target-specific cfg values:\n{cfg_text}\n");
section(&Some(cfg_text), "cfg");
doc.push_str(&format!("## cfg\n{cfg_text}\n"));
doc
}
@ -158,51 +169,16 @@ But as you might notice, all targets are actually present with a stub :3.
// TODO: Render the nice table showing off all targets and their tier.
}
#[derive(Debug, serde::Deserialize)]
#[serde(deny_unknown_fields)]
struct TargetInfoTable {
target: Vec<TargetInfoPattern>,
}
#[derive(Debug, serde::Deserialize)]
#[serde(deny_unknown_fields)]
struct TargetInfoPattern {
pattern: String,
#[serde(default)]
maintainers: Vec<String>,
tier: Option<u8>,
requirements: Option<String>,
testing: Option<String>,
building_the_target: Option<String>,
cross_compilation: Option<String>,
building_rust_programs: Option<String>,
}
struct TargetPatternEntry {
info: TargetInfoPattern,
info: ParsedTargetInfoFile,
used: bool,
}
fn load_target_info_patterns() -> Vec<TargetPatternEntry> {
let file = include_str!("../target_info.toml");
let table = toml::from_str::<TargetInfoTable>(file).unwrap();
table
.target
.into_iter()
.map(|info| TargetPatternEntry { info, used: false })
.collect()
}
/// Gets the target information from `target_info.toml` by applying all patterns that match.
fn target_info(info_patterns: &mut [TargetPatternEntry], target: &str) -> TargetDocs {
let mut tier = None;
let mut maintainers = Vec::new();
let mut requirements = None;
let mut testing = None;
let mut building_the_target = None;
let mut cross_compilation = None;
let mut building_rust_programs = None;
let mut sections = Vec::new();
for target_pattern in info_patterns {
if glob_match::glob_match(&target_pattern.info.pattern, target) {
@ -211,41 +187,28 @@ fn target_info(info_patterns: &mut [TargetPatternEntry], target: &str) -> Target
maintainers.extend_from_slice(&target_pattern.maintainers);
fn set_once<T: Clone>(
target: &str,
pattern_value: &Option<T>,
to_insert: &mut Option<T>,
name: &str,
) {
if let Some(pattern_value) = pattern_value {
if to_insert.is_some() {
panic!("target {target} inherits a {name} from multiple patterns, create a more specific pattern and add it there");
if let Some(pattern_value) = &target_pattern.tier {
if tier.is_some() {
panic!("target {target} inherits a tier from multiple patterns, create a more specific pattern and add it there");
}
*to_insert = Some(pattern_value.clone());
tier = Some(pattern_value.clone());
}
for (section_name, content) in &target_pattern.sections {
if sections.iter().any(|(name, _)| name == section_name) {
panic!("target {target} inherits the section {section_name} from multiple patterns, create a more specific pattern and add it there");
}
sections.push((section_name.clone(), content.clone()));
}
#[rustfmt::skip]
{
set_once(target, &target_pattern.tier, &mut tier, "tier");
set_once(target, &target_pattern.requirements, &mut requirements, "requirements");
set_once(target, &target_pattern.testing, &mut testing, "testing");
set_once(target, &target_pattern.building_the_target, &mut building_the_target, "building_the_target");
set_once(target, &target_pattern.cross_compilation, &mut cross_compilation, "cross_compilation");
set_once(target, &target_pattern.building_rust_programs, &mut building_rust_programs, "building_rust_programs");
};
}
}
TargetDocs {
name: target.to_owned(),
maintainers,
requirements,
testing,
building_the_target,
cross_compilation,
building_rust_programs,
// tier: tier.expect(&format!("no tier found for target {target}")),
tier: tier.unwrap_or(0),
tier: tier.unwrap_or("UNKNOWN".to_owned()),
sections,
}
}

179
src/parse.rs Normal file
View file

@ -0,0 +1,179 @@
//! Suboptimal half-markdown parser that's just good-enough for this.
use eyre::{bail, OptionExt, Result, WrapErr};
use std::{fs::DirEntry, path::Path};
#[derive(Debug, PartialEq)]
pub struct ParsedTargetInfoFile {
pub pattern: String,
pub tier: Option<String>,
pub maintainers: Vec<String>,
pub sections: Vec<(String, String)>,
}
#[derive(serde::Deserialize)]
struct Frontmatter {
tier: Option<String>,
#[serde(default)]
maintainers: Vec<String>,
}
pub fn load_target_infos(directory: &Path) -> Result<Vec<ParsedTargetInfoFile>> {
let dir = std::fs::read_dir(directory).unwrap();
let mut infos = Vec::new();
for entry in dir {
let entry = entry?;
infos.push(
load_single_target_info(&entry)
.wrap_err_with(|| format!("loading {}", entry.path().display()))?,
)
}
Ok(infos)
}
fn load_single_target_info(entry: &DirEntry) -> Result<ParsedTargetInfoFile> {
let pattern = entry.file_name();
let name = pattern
.to_str()
.ok_or_eyre("file name is invalid utf8")?
.strip_suffix(".md")
.ok_or_eyre("target_info files must end with .md")?;
let content: String = std::fs::read_to_string(entry.path()).wrap_err("reading content")?;
parse_file(name, &content)
}
fn parse_file(name: &str, content: &str) -> Result<ParsedTargetInfoFile> {
let mut frontmatter_splitter = content.split("---\n");
let frontmatter = frontmatter_splitter
.nth(1)
.ok_or_eyre("missing frontmatter")?;
let frontmatter =
serde_yaml::from_str::<Frontmatter>(frontmatter).wrap_err("invalid frontmatter")?;
let body = frontmatter_splitter.next().ok_or_eyre("no body")?;
let mut sections = Vec::new();
for line in body.lines() {
if line.starts_with("#") {
if let Some(header) = line.strip_prefix("## ") {
if !crate::SECTIONS.contains(&header) {
bail!(
"`{header}` is not an allowed section name, must be one of {:?}",
super::SECTIONS
);
}
sections.push((header.to_owned(), String::new()));
} else {
bail!("the only allowed headings are `## `");
}
} else {
match sections.last_mut() {
Some((_, content)) => {
content.push_str(line);
content.push('\n');
}
None if line.trim().is_empty() => {}
None => bail!("line with content not allowed before the first heading"),
}
}
}
sections
.iter_mut()
.for_each(|section| section.1 = section.1.trim().to_owned());
Ok(ParsedTargetInfoFile {
pattern: name.to_owned(),
maintainers: frontmatter.maintainers,
tier: frontmatter.tier,
sections,
})
}
#[cfg(test)]
mod tests {
#[test]
fn no_frontmatter() {
let name = "archlinux-unknown-linux-gnu.md"; // arch linux is an arch, right?
let content = "";
assert!(super::parse_file(name, content).is_err());
}
#[test]
fn invalid_section() {
let name = "6502-nintendo-nes.md";
let content = "
---
---
## Not A Real Section
";
assert!(super::parse_file(name, content).is_err());
}
#[test]
fn wrong_header() {
let name = "x86_64-known-linux-gnu.md";
let content = "
---
---
# x86_64-known-linux-gnu
";
assert!(super::parse_file(name, content).is_err());
}
#[test]
fn parse_correctly() {
let name = "cat-unknown-linux-gnu.md";
let content = r#"
---
tier: "1" # first-class cats
maintainers: ["who maintains the cat?"]
---
## Requirements
This target mostly just meows and doesn't do much.
## Testing
You can pet the cat and it might respond positively.
## Cross compilation
If you're on a dog system, there might be conflicts with the cat, be careful.
But it should be possible.
"#;
let info = super::parse_file(name, content).unwrap();
assert_eq!(info.maintainers, vec!["who maintains the cat?"]);
assert_eq!(info.pattern, name);
assert_eq!(info.tier, Some("1".to_owned()));
assert_eq!(
info.sections,
vec![
(
"Requirements".to_owned(),
"This target mostly just meows and doesn't do much.".to_owned(),
),
(
"Testing".to_owned(),
"You can pet the cat and it might respond positively.".to_owned(),
),
(
"Cross compilation".to_owned(),
"If you're on a dog system, there might be conflicts with the cat, be careful.\nBut it should be possible.".to_owned(),
),
]
);
}
}

34
target_info/*-apple-tvos.md Normal file
View file

@ -0,0 +1,34 @@
---
tier: "2"
maintainers: ["@thomcc"]
---
## Requirements
These targets are cross-compiled. You will need appropriate versions of Xcode and the SDKs for tvOS (AppleTVOS.sdk) and/or the tvOS Simulator (AppleTVSimulator.sdk) to build a toolchain and target these platforms.
The targets support most (see below) of the standard library including the allocator to the best of my knowledge, however they are very new, not yet well-tested, and it is possible that there are various bugs.
In theory we support back to tvOS version 7.0, although the actual minimum version you can target may be newer than this, for example due to the versions of Xcode and your SDKs.
As with the other Apple targets, rustc respects the common environment variables used by Xcode to configure this, in this case TVOS_DEPLOYMENT_TARGET.
Incompletely supported library functionality
As mentioned, "most" of the standard library is supported, which means that some portions are known to be unsupported. The following APIs are currently known to have missing or incomplete support:
std::process::Command's API will return an error if it is configured in a manner which cannot be performed using posix_spawn
-- this is because the more flexible fork/exec-based approach is prohibited on these platforms in favor of posix_spawn{,p}
(which still probably will get you rejected from app stores, so is likely sideloading-only).
A concrete set of cases where this will occur is difficult to enumerate (and would quickly become stale), but in some cases it may be worked around by tweaking the manner in which Command is invoked.
## Testing
There is no support for running the Rust or standard library testsuite on tvOS or the simulators at the moment. Testing has mostly been done manually with builds of static libraries called from Xcode or a simulator.
It hopefully will be possible to improve this in the future.
## Cross compilation
This target can be cross-compiled from x86_64 or aarch64 macOS hosts.
Other hosts are not supported for cross-compilation, but might work when also providing the required Xcode SDK.

19
target_info/powerpc64-ibm-aix.md Normal file
View file

@ -0,0 +1,19 @@
---
tier: "3"
maintainers: [
"QIU Chaofan `qiucofan@cn.ibm.com`, https://github.com/ecnelises",
"Kai LUO, `lkail@cn.ibm.com`, https://github.com/bzEq",
]
---
## Requirements
This target supports host tools, std and alloc. This target cannot be cross-compiled as for now, mainly because of the unavailability of system linker on other platforms.
Binary built for this target is expected to run on Power7 or newer CPU, and AIX 7.2 or newer version.
Binary format of this platform is XCOFF. Archive file format is 'AIX big format'.
## Testing
This target supports running test suites natively, but it's not available to cross-compile and execute in emulator.