Skip to main content

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}