apple_platforms/lib.rs
1//! Apple platform metadata, target-triple conversion, and SDK name resolution.
2//!
3//! This crate provides a typed Rust representation of every Apple platform
4//! defined in [LLVM's `MachO.def`][llvm-macho] — macOS, iOS, tvOS, watchOS,
5//! visionOS, Mac Catalyst, DriverKit, BridgeOS, and their simulator variants —
6//! together with utilities for converting Rust target triples to the strings
7//! that Apple's toolchain expects.
8//!
9//! It is primarily intended for use in `build.rs` scripts that invoke `swiftc`,
10//! `xcrun`, or `clang`.
11//!
12//! [llvm-macho]: https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/BinaryFormat/MachO.def
13//!
14//! # Quick start
15//!
16//! ```
17//! use apple_platforms::{ApplePlatform, triple};
18//!
19//! // Parse a Rust target triple into a typed platform value
20//! let p = ApplePlatform::from_rust_triple("aarch64-apple-ios-sim").unwrap();
21//! assert_eq!(p, ApplePlatform::IOSSimulator);
22//!
23//! // SDK name for `xcrun --sdk <name>`
24//! assert_eq!(p.sdk(), Some("iphonesimulator"));
25//!
26//! // Navigate sim ↔ device
27//! assert_eq!(p.device(), ApplePlatform::IOS);
28//! assert_eq!(ApplePlatform::IOS.simulator(), Some(ApplePlatform::IOSSimulator));
29//!
30//! // Access full LLVM-sourced metadata
31//! let meta = p.metadata();
32//! assert_eq!(meta.marketing, "iOS Simulator");
33//! assert_eq!(meta.tapi_target, "ios-simulator");
34//!
35//! // String-only path — useful when you only need strings
36//! assert_eq!(triple::to_clang("aarch64-apple-darwin"), Some("arm64-apple-macosx"));
37//! assert_eq!(triple::to_sdk("aarch64-apple-ios"), Some("iphoneos"));
38//! ```
39//!
40//! # Modules
41//!
42//! | Module | Contents |
43//! |--------|----------|
44//! | [`platform`] | [`ApplePlatform`] enum, [`Platform`] metadata struct, [`ParsePlatformError`] |
45//! | [`triple`] | [`triple::to_clang`], [`triple::to_sdk`] free functions, [`triple::Architecture`] |
46//!
47//! # Typical `build.rs` pattern
48//!
49//! ```rust,ignore
50//! fn main() {
51//! let target = std::env::var("TARGET").unwrap();
52//!
53//! let Some(clang_triple) = apple_platforms::triple::to_clang(&target) else {
54//! return; // not an Apple target
55//! };
56//!
57//! let platform = apple_platforms::ApplePlatform::from_rust_triple(&target).unwrap();
58//! let sdk_name = platform.sdk().unwrap_or("macosx");
59//!
60//! // Pass to xcrun / swiftc / clang …
61//! }
62//! ```
63
64pub mod platform;
65pub mod triple;
66
67// ── Top-level re-exports ─────────────────────────────────────────────────────
68
69pub use platform::{ApplePlatform, ParsePlatformError, Platform};
70
71// ── Prelude ───────────────────────────────────────────────────────────────────
72
73/// Convenience re-exports for glob import (`use apple_platforms::prelude::*`).
74///
75/// Brings in the types you'll need most often:
76///
77/// ```
78/// use apple_platforms::prelude::*;
79///
80/// let p = ApplePlatform::MacOS;
81/// assert_eq!(p.sdk(), Some("macosx"));
82/// assert_eq!(to_sdk("aarch64-apple-darwin"), Some("macosx"));
83/// ```
84pub mod prelude {
85 pub use super::platform::{ApplePlatform, ParsePlatformError, Platform};
86 pub use super::triple::{to_clang, to_sdk, Architecture};
87}