quack_rs/validate/platform.rs
1// SPDX-License-Identifier: MIT
2// Copyright 2026 Tom F. <https://github.com/tomtom215/>
3// My way of giving something small back to the open source community
4// and encouraging more Rust development!
5
6//! `DuckDB` build platform validation.
7//!
8//! `DuckDB` community extensions must build for a standard set of platforms.
9//! Extensions that cannot support a platform must declare it in
10//! `extension.excluded_platforms`. This module validates those declarations.
11//!
12//! # Reference
13//!
14//! The list below is derived from `config/distribution_matrix.json` in
15//! [`duckdb/extension-ci-tools`], which is the file the community-extensions
16//! build actually reads. `scripts/check-platform-table.py` re-derives it and
17//! fails CI when the two diverge, because a stale list is worse than none: it
18//! rejects platforms that exist and accepts ones that do not.
19//!
20//! [`duckdb/extension-ci-tools`]: https://github.com/duckdb/extension-ci-tools/blob/main/config/distribution_matrix.json
21
22use crate::error::ExtensionError;
23
24/// Every platform identifier [`validate_platform`] recognises.
25///
26/// This is [`DUCKDB_CI_PLATFORMS`] — the architectures the community-extension
27/// CI builds — plus names that appear in real, accepted `description.yml`
28/// files and are therefore not errors:
29///
30/// - **`windows_amd64_rtools`**, the name older `DuckDB` releases gave the
31/// R-tools Windows build. `DuckDBPlatform()` in v1.5.5's
32/// `duckdb/common/platform.hpp` maps `DUCKDB_PLATFORM_RTOOLS` to the
33/// `_mingw` suffix instead, so current builds report `windows_amd64_mingw`;
34/// the old name is not in the distribution matrix either, but 84 of the 346
35/// extensions in `duckdb/community-extensions` (commit `5ae7df8`,
36/// 2026-09-23) still exclude it.
37/// - **`windows_arm64_mingw`**, which v1.5.5's `DuckDBPlatform()` produces for
38/// a MinGW build on arm64 (`_mingw` postfix on the `arm64` arch). Not in the
39/// distribution matrix; three of those 346 extensions exclude it.
40/// - **The group names** in [`DUCKDB_PLATFORM_GROUPS`] — `linux`, `osx`,
41/// `wasm`, `windows` — which are the top-level keys of
42/// `distribution_matrix.json` and appear in at least one published
43/// extension's exclusion list. They are accepted, not meaningful: see
44/// [`DUCKDB_PLATFORM_GROUPS`].
45///
46/// An extension must either build for all of the non-opt-in CI platforms or
47/// declare the ones it cannot in `extension.excluded_platforms`.
48///
49/// `linux_amd64_gcc4` is **not** here — see [`DUCKDB_RETIRED_PLATFORMS`].
50pub const DUCKDB_PLATFORMS: &[&str] = &[
51 "linux",
52 "linux_amd64",
53 "linux_amd64_musl",
54 "linux_arm64",
55 "linux_arm64_musl",
56 "osx",
57 "osx_amd64",
58 "osx_arm64",
59 "wasm",
60 "wasm_eh",
61 "wasm_mvp",
62 "wasm_threads",
63 "windows",
64 "windows_amd64",
65 "windows_amd64_mingw",
66 "windows_amd64_rtools",
67 "windows_arm64",
68 "windows_arm64_mingw",
69];
70
71/// The platforms the community-extension CI actually builds.
72///
73/// Exactly the `duckdb_arch` values in `distribution_matrix.json`, kept in sync
74/// by `scripts/check-platform-table.py`. [`DUCKDB_PLATFORMS`] is a superset:
75/// see its documentation for what else is a legal name.
76pub const DUCKDB_CI_PLATFORMS: &[&str] = &[
77 "linux_amd64",
78 "linux_amd64_musl",
79 "linux_arm64",
80 "linux_arm64_musl",
81 "osx_amd64",
82 "osx_arm64",
83 "wasm_eh",
84 "wasm_mvp",
85 "wasm_threads",
86 "windows_amd64",
87 "windows_amd64_mingw",
88 "windows_arm64",
89];
90
91/// Platforms `DuckDB` no longer builds, which [`validate_excluded_platforms`]
92/// nevertheless accepts.
93///
94/// `linux_amd64_gcc4` was the legacy-CXX-ABI Linux target. `DuckDB` retired it:
95/// `DuckDBPlatform()` in `duckdb/common/platform.hpp` now raises a compile
96/// error for that ABI rather than emitting a `_gcc4` suffix, and it is absent
97/// from the distribution matrix. Excluding it is therefore a no-op — and three
98/// published extensions still do, so rejecting it would reject files the
99/// community build accepts. [`validate_platform`] still rejects it, since
100/// nothing can *target* it.
101pub const DUCKDB_RETIRED_PLATFORMS: &[&str] = &["linux_amd64_gcc4"];
102
103/// The group names `distribution_matrix.json` organises its architectures
104/// under, which appear in real `excluded_platforms` fields.
105///
106/// **A group name excludes nothing.** The community build removes a platform
107/// only when its exact `duckdb_arch` is listed (`arch in excluded_arch_values`
108/// in `extension-ci-tools`' `scripts/modify_distribution_matrix.py`, the same
109/// on `v1.4-andium`, `v1.5-variegata`, `main` and `v2.0-cyanoptera`), so
110/// `excluded_platforms: "wasm"` leaves `wasm_eh`, `wasm_mvp` and
111/// `wasm_threads` building. The names are accepted because rejecting them would
112/// reject files the build accepts; [`parse_description_yml`] warns about them.
113///
114/// [`parse_description_yml`]: crate::validate::description_yml::parse_description_yml
115pub const DUCKDB_PLATFORM_GROUPS: &[&str] = &["linux", "osx", "wasm", "windows"];
116
117/// The [`DUCKDB_CI_PLATFORMS`] that are **opt-in**: the community CI does not
118/// build them unless an extension asks for them.
119///
120/// Listing one of these in `excluded_platforms` has no effect — it was never
121/// going to be built. [`validate_excluded_platforms`] accepts them anyway,
122/// since a redundant exclusion is not an error, but
123/// [`is_opt_in_platform`] lets a caller warn about it.
124///
125/// `osx_amd64` became opt-in in `extension-ci-tools` for `DuckDB` 2.0 ("Disable
126/// `osx_amd64` unless explicitly opted in"); `DuckDB` 2.1 drops the platform.
127pub const DUCKDB_OPT_IN_PLATFORMS: &[&str] = &[
128 "linux_amd64_musl",
129 "linux_arm64_musl",
130 "osx_amd64",
131 "windows_arm64",
132];
133
134/// Returns `true` if `platform` is only built when an extension opts into it.
135///
136/// # Example
137///
138/// ```rust
139/// use quack_rs::validate::platform::is_opt_in_platform;
140///
141/// assert!(is_opt_in_platform("linux_arm64_musl"));
142/// assert!(!is_opt_in_platform("linux_amd64"));
143/// ```
144#[must_use]
145pub fn is_opt_in_platform(platform: &str) -> bool {
146 DUCKDB_OPT_IN_PLATFORMS.contains(&platform)
147}
148
149/// Validates that a platform identifier is a known `DuckDB` build target.
150///
151/// # Errors
152///
153/// Returns `ExtensionError` if the platform is empty or not in [`DUCKDB_PLATFORMS`].
154///
155/// # Example
156///
157/// ```rust
158/// use quack_rs::validate::validate_platform;
159///
160/// assert!(validate_platform("linux_amd64").is_ok());
161/// assert!(validate_platform("osx_arm64").is_ok());
162/// assert!(validate_platform("wasm_eh").is_ok());
163/// assert!(validate_platform("linux_arm64_musl").is_ok());
164/// assert!(validate_platform("windows_arm32").is_err());
165/// // Retired upstream — DuckDB no longer builds it.
166/// assert!(validate_platform("linux_amd64_gcc4").is_err());
167/// assert!(validate_platform("").is_err());
168/// ```
169pub fn validate_platform(platform: &str) -> Result<(), ExtensionError> {
170 if platform.is_empty() {
171 return Err(ExtensionError::new("platform identifier must not be empty"));
172 }
173
174 if DUCKDB_PLATFORMS.contains(&platform) {
175 return Ok(());
176 }
177 // The one stale name worth naming: it appears in older DuckDB
178 // documentation and in extensions written against it.
179 if platform == "linux_amd64_gcc4" {
180 return Err(ExtensionError::new(
181 "platform 'linux_amd64_gcc4' no longer exists; DuckDB retired the legacy \
182 CXX ABI target and no longer builds it (excluding it is a harmless no-op).",
183 ));
184 }
185 // Only the platforms the community CI builds: the group names and the
186 // legacy names `DUCKDB_PLATFORMS` also accepts are not targets.
187 Err(ExtensionError::new(format!(
188 "platform '{platform}' is not a recognized DuckDB build target; the community CI \
189 builds: {}",
190 DUCKDB_CI_PLATFORMS.join(", ")
191 )))
192}
193
194/// The platforms `group` (one of [`DUCKDB_PLATFORM_GROUPS`]) stands for, as
195/// the community CI builds them: `wasm` is `wasm_eh`, `wasm_mvp` and
196/// `wasm_threads`.
197pub(crate) fn platforms_in_group(group: &str) -> Vec<&'static str> {
198 DUCKDB_CI_PLATFORMS
199 .iter()
200 .copied()
201 .filter(|p| {
202 p.strip_prefix(group)
203 .is_some_and(|rest| rest.starts_with('_'))
204 })
205 .collect()
206}
207
208/// Validates a list of excluded platform identifiers.
209///
210/// Each platform must be a known `DuckDB` build target or one of
211/// [`DUCKDB_RETIRED_PLATFORMS`] (excluding a platform that is no longer built
212/// is a harmless no-op). Duplicates are flagged as an error.
213///
214/// # Errors
215///
216/// Returns `ExtensionError` on the first invalid or duplicate platform.
217///
218/// # Example
219///
220/// ```rust
221/// use quack_rs::validate::platform::validate_excluded_platforms;
222///
223/// assert!(validate_excluded_platforms(&["wasm_mvp", "wasm_eh"]).is_ok());
224/// assert!(validate_excluded_platforms(&["invalid_platform"]).is_err());
225/// assert!(validate_excluded_platforms(&["linux_amd64", "linux_amd64"]).is_err());
226/// ```
227pub fn validate_excluded_platforms(platforms: &[&str]) -> Result<(), ExtensionError> {
228 let mut seen = std::collections::HashSet::new();
229 for &platform in platforms {
230 // A trailing ';' is common in real files and yields an empty segment;
231 // it means nothing, so it is skipped rather than reported as a bogus
232 // platform named "".
233 if platform.is_empty() {
234 continue;
235 }
236 if !DUCKDB_RETIRED_PLATFORMS.contains(&platform) {
237 validate_platform(platform)?;
238 }
239 if !seen.insert(platform) {
240 return Err(ExtensionError::new(format!(
241 "duplicate excluded platform: '{platform}'"
242 )));
243 }
244 }
245 Ok(())
246}
247
248#[cfg(test)]
249mod tests {
250 use super::*;
251
252 #[test]
253 fn all_platforms_valid() {
254 for &platform in DUCKDB_PLATFORMS {
255 assert!(
256 validate_platform(platform).is_ok(),
257 "expected '{platform}' to be valid"
258 );
259 }
260 }
261
262 #[test]
263 fn linux_amd64_valid() {
264 assert!(validate_platform("linux_amd64").is_ok());
265 }
266
267 #[test]
268 fn osx_arm64_valid() {
269 assert!(validate_platform("osx_arm64").is_ok());
270 }
271
272 #[test]
273 fn wasm_valid() {
274 assert!(validate_platform("wasm_mvp").is_ok());
275 assert!(validate_platform("wasm_eh").is_ok());
276 assert!(validate_platform("wasm_threads").is_ok());
277 }
278
279 #[test]
280 fn empty_rejected() {
281 assert!(validate_platform("").is_err());
282 }
283
284 #[test]
285 fn unknown_platform_rejected() {
286 // `DuckDBPlatform()` can emit "freebsd_amd64", but the community CI
287 // never builds it, so it cannot be excluded from a build that does not
288 // happen.
289 let err = validate_platform("freebsd_amd64").unwrap_err();
290 assert!(err.as_str().contains("not a recognized"));
291 }
292
293 #[test]
294 fn retired_gcc4_platform_says_why() {
295 let err = validate_platform("linux_amd64_gcc4").unwrap_err();
296 assert!(
297 err.as_str().contains("no longer exists"),
298 "a stale name deserves a better message than \"not recognized\": {err}"
299 );
300 }
301
302 #[test]
303 fn musl_platforms_are_recognised() {
304 // Present in extension-ci-tools' distribution_matrix.json as opt-in
305 // targets; rejecting them made a legitimate exclusion un-declarable.
306 assert!(validate_platform("linux_amd64_musl").is_ok());
307 assert!(validate_platform("linux_arm64_musl").is_ok());
308 assert!(validate_excluded_platforms(&["linux_arm64_musl"]).is_ok());
309 }
310
311 #[test]
312 fn opt_in_platforms_are_a_subset() {
313 for &platform in DUCKDB_OPT_IN_PLATFORMS {
314 assert!(
315 DUCKDB_PLATFORMS.contains(&platform),
316 "{platform} is opt-in but not a known platform"
317 );
318 assert!(is_opt_in_platform(platform));
319 }
320 assert!(!is_opt_in_platform("linux_amd64"));
321 }
322
323 #[test]
324 fn platform_list_has_no_duplicates() {
325 let unique: std::collections::HashSet<_> = DUCKDB_PLATFORMS.iter().collect();
326 assert_eq!(unique.len(), DUCKDB_PLATFORMS.len());
327 }
328
329 #[test]
330 fn validate_excluded_platforms_valid() {
331 assert!(validate_excluded_platforms(&["wasm_mvp", "wasm_eh"]).is_ok());
332 }
333
334 #[test]
335 fn validate_excluded_platforms_empty() {
336 assert!(validate_excluded_platforms(&[]).is_ok());
337 }
338
339 #[test]
340 fn validate_excluded_platforms_invalid() {
341 assert!(validate_excluded_platforms(&["invalid"]).is_err());
342 }
343
344 /// `DuckDBPlatform()` in v1.5.5 emits `windows_arm64_mingw` (MinGW on
345 /// arm64), and two published extensions exclude it.
346 #[test]
347 fn windows_arm64_mingw_is_a_platform() {
348 assert!(validate_platform("windows_arm64_mingw").is_ok());
349 assert!(validate_excluded_platforms(&["windows_arm64_mingw"]).is_ok());
350 }
351
352 /// Excluding a platform that is no longer built is a no-op, not an error:
353 /// three published extensions still list `linux_amd64_gcc4`.
354 #[test]
355 fn a_retired_platform_may_be_excluded() {
356 assert!(validate_excluded_platforms(&["linux_amd64_gcc4", "wasm_mvp"]).is_ok());
357 assert!(
358 crate::validate::validate_excluded_platforms_str("wasm_mvp;linux_amd64_gcc4;").is_ok()
359 );
360 // ...but it is still not a platform anyone can target.
361 assert!(validate_platform("linux_amd64_gcc4").is_err());
362 assert!(validate_excluded_platforms(&["linux_amd64_gcc4", "linux_amd64_gcc4"]).is_err());
363 }
364
365 #[test]
366 fn validate_excluded_platforms_duplicate() {
367 let err = validate_excluded_platforms(&["linux_amd64", "linux_amd64"]).unwrap_err();
368 assert!(err.as_str().contains("duplicate"));
369 }
370}