Skip to main content

quack_rs/scaffold/
mod.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//! Project scaffolding for `DuckDB` Rust extensions.
7//!
8//! Generates the complete file set needed to build and submit a `DuckDB` extension
9//! to the community extensions repository — **without any C++ glue**.
10//!
11//! # Background
12//!
13//! The `DuckDB` C Extension API (used by the official
14//! [`extension-template-rs`](https://github.com/duckdb/extension-template-rs))
15//! allows pure-Rust extensions that need only:
16//!
17//! - `Cargo.toml` (cdylib, `quack-rs` + `libduckdb-sys` deps)
18//! - `Makefile` (delegates to `cargo build` + metadata scripts from `extension-ci-tools`)
19//! - `src/lib.rs` (entry point + function registration)
20//! - `extension-ci-tools/` (git submodule for CI/CD)
21//! - `description.yml` (extension metadata for community submission)
22//!
23//! This module generates all of these from a [`ScaffoldConfig`], plus a
24//! `SQLLogicTest`, two GitHub Actions workflows (fast native checks, and the
25//! extension-ci-tools distribution build for every community platform), a
26//! `README.md`, the license text, a `cargo-deny` configuration, the
27//! `docs/function_descriptions.csv` the community documentation site reads,
28//! and the supporting dotfiles. The `quack_scaffold` binary
29//! (`cargo install quack-rs --bin quack_scaffold`) writes them to disk.
30//!
31//! # Example
32//!
33//! ```rust
34//! use quack_rs::scaffold::{ScaffoldConfig, generate_scaffold_with_warnings};
35//!
36//! let config = ScaffoldConfig {
37//!     name: "my_analytics".to_string(),
38//!     description: "Fast analytics functions for DuckDB".to_string(),
39//!     version: "0.1.0".to_string(),
40//!     license: "MIT".to_string(),
41//!     maintainer: "Jane Doe".to_string(),
42//!     github_repo: "janedoe/duckdb-my-analytics".to_string(),
43//!     // `excluded_platforms` defaults to DEFAULT_EXCLUDED_PLATFORMS.
44//!     ..ScaffoldConfig::default()
45//! };
46//!
47//! let scaffold = generate_scaffold_with_warnings(&config).unwrap();
48//! let files = &scaffold.files;
49//! assert!(files.iter().any(|f| f.path == "Cargo.toml"));
50//! assert!(files.iter().any(|f| f.path == "Makefile"));
51//! assert!(files.iter().any(|f| f.path == "src/lib.rs"));
52//! assert!(files.iter().any(|f| f.path == "description.yml"));
53//! assert!(scaffold.warnings.is_empty());
54//! ```
55
56mod checks;
57mod escape;
58mod licenses;
59mod templates;
60mod templates_ci;
61mod templates_docs;
62mod templates_make;
63
64#[cfg(test)]
65mod tests;
66#[cfg(test)]
67mod tests_content;
68#[cfg(test)]
69mod tests_escaping;
70#[cfg(test)]
71mod tests_generated;
72// Runs `make`, `git` and a shell script: Unix only. Two attributes rather than
73// `cfg(all(test, unix))`: cargo-mutants skips a module only when it sees a plain
74// `#[cfg(test)]`, and otherwise mutates this file's helpers.
75#[cfg(test)]
76#[cfg(unix)]
77mod tests_make;
78#[cfg(test)]
79mod tests_workflows;
80
81use crate::error::ExtensionError;
82#[cfg(test)]
83use checks::libduckdb_sys_requirement;
84
85/// Configuration for generating a new extension project.
86#[derive(Debug, Clone)]
87pub struct ScaffoldConfig {
88    /// Extension name (must pass
89    /// [`validate_community_extension_name`][crate::validate::validate_community_extension_name]:
90    /// well formed, and not a `DuckDB` alias such as `s3` or a core extension
91    /// name such as `json`).
92    pub name: String,
93    /// Short description of the extension.
94    ///
95    /// Free text: YAML punctuation such as `: ` or ` #`, quotes, backslashes
96    /// and non-ASCII text are quoted and escaped in `description.yml`, and each
97    /// line becomes a `//!` line in `src/lib.rs`. It must not be empty, start
98    /// or end with whitespace, or contain control characters other than
99    /// newline and tab (or Unicode bidirectional controls).
100    pub description: String,
101    /// Initial version: semver without a leading `v` (e.g. `"0.1.0"`),
102    /// because it is the `[package] version` of the generated `Cargo.toml`
103    /// (and `cargo` refuses anything else) as well as the version in
104    /// `description.yml`. Must pass [`validate_semver`][crate::validate::validate_semver],
105    /// with every numeric part at most `u64::MAX` (what Cargo can read).
106    pub version: String,
107    /// The license: an SPDX identifier or expression such as `MIT OR
108    /// Apache-2.0`. One that [`validate_spdx_license`][crate::validate::validate_spdx_license]
109    /// accepts is used as is; a well-formed one naming an identifier outside
110    /// its shortlist (`BUSL-1.1`, `CC0-1.0`) is accepted with a warning, since
111    /// the shortlist is not the SPDX registry. Line breaks and other
112    /// whitespace are written as single spaces.
113    ///
114    /// The scaffold writes the license text for `MIT`, `Apache-2.0`,
115    /// `BSD-2-Clause`, `BSD-3-Clause`, `ISC`, `0BSD`, `MIT-0` and `Unlicense`
116    /// (`LICENSE`, or `LICENSE-<ID>` for each in an expression), and a
117    /// `LICENSE.TODO` naming the text to add for anything else.
118    pub license: String,
119    /// Primary maintainer name: a single non-empty line, quoted and escaped in
120    /// `description.yml` like [`description`][Self::description].
121    pub maintainer: String,
122    /// GitHub repository path (e.g., `"myorg/duckdb-my-ext"`): `owner/repo`,
123    /// in the characters GitHub allows.
124    pub github_repo: String,
125    /// Platforms the community build skips: written as `excluded_platforms`
126    /// in `description.yml` and as `exclude_archs` in the generated
127    /// distribution workflow, so the two always agree.
128    ///
129    /// Defaults to [`DEFAULT_EXCLUDED_PLATFORMS`]; an empty list builds for
130    /// every platform.
131    pub excluded_platforms: Vec<String>,
132    /// Value written as `TARGET_DUCKDB_VERSION` in the generated `Makefile`.
133    ///
134    /// `extension-ci-tools` passes this to `append_extension_metadata.py -dv`,
135    /// and its meaning depends on [`use_unstable_c_api`][Self::use_unstable_c_api]:
136    ///
137    /// - `false` → the **C extension API** version. The extension is stamped
138    ///   `C_STRUCT` and loads into any `DuckDB` whose C API version is at least
139    ///   this. One of:
140    ///   - [`DUCKDB_API_VERSION`][crate::DUCKDB_API_VERSION] (`"v1.2.0"`), for
141    ///     an extension that stays off quack-rs's `duckdb-1-5*` features. It
142    ///     loads into every `DuckDB` from v1.2.0, 2.0.0 included.
143    ///   - [`DUCKDB_API_VERSION_1_5_6`][crate::DUCKDB_API_VERSION_1_5_6]
144    ///     (`"v1.5.6"`), for one that uses them. `DuckDB` v1.5.6 and v2.0.0
145    ///     load it and older releases refuse it. The generated `Cargo.toml`
146    ///     pins `libduckdb-sys` to the v1.5.6 bindings (`~1.10506.0`), whose
147    ///     layout both releases share, and the `Makefile` refuses to build when
148    ///     the resolved bindings are for another release.
149    /// - `true` → an exact **`DuckDB` 1.x release**, e.g. `"v1.5.5"`. The
150    ///   extension is stamped `C_STRUCT_UNSTABLE` and `DuckDB` refuses to load
151    ///   it into any other release. The generated `Cargo.toml` then pins
152    ///   `libduckdb-sys` to that release's bindings (`~1.10505.0` for v1.5.5),
153    ///   the `Makefile` tests against it (`DUCKDB_TEST_VERSION`) and refuses to
154    ///   build when the resolved bindings and `TARGET_DUCKDB_VERSION` disagree.
155    ///   A 2.x release is refused: `DuckDB` 2.0 loads a `C_STRUCT_UNSTABLE`
156    ///   binary only through the C API v2 entry point, which quack-rs does not
157    ///   generate.
158    ///
159    /// Defaults to [`DUCKDB_API_VERSION`][crate::DUCKDB_API_VERSION].
160    pub target_duckdb_version: String,
161    /// Whether the generated `Makefile` sets `USE_UNSTABLE_C_API=1`, pinning
162    /// the binary to one `DuckDB` 1.x release.
163    ///
164    /// An extension that enables quack-rs's `duckdb-1-5`, `duckdb-1-5-3` or
165    /// `duckdb-1-5-4` features calls C API functions past the stable prefix of
166    /// `duckdb_ext_api_v1`, so `DuckDB` must not load it into a release with a
167    /// different layout (see [`crate::abi`]). The way to ensure that which
168    /// also works on `DuckDB` 2.0 is to leave this `false` and set
169    /// [`target_duckdb_version`][Self::target_duckdb_version] to
170    /// [`DUCKDB_API_VERSION_1_5_6`][crate::DUCKDB_API_VERSION_1_5_6]. Set this
171    /// only to target one release older than v1.5.6.
172    ///
173    /// Defaults to `false`.
174    pub use_unstable_c_api: bool,
175    /// Value written as `repo.ref` in the generated `description.yml`.
176    ///
177    /// **Must be a commit hash**, not a branch. `DuckDB`'s community-extension
178    /// documentation is explicit — "Provide the hash of the latest commit on
179    /// the branch targeting stable as `ref`" — because the repository builds
180    /// exactly this revision and signs the result, so a moving reference would
181    /// make the build unreproducible. Of the 395 `description.yml` files in
182    /// `duckdb/community-extensions` at commit `845779e`, 384 pin a full
183    /// 40-character hash and 11 a tag; none uses a branch. Letters, digits,
184    /// `-`, `_`, `.` and `/` only.
185    ///
186    /// Defaults to [`REF_PLACEHOLDER`], which is deliberately not a valid
187    /// revision so it cannot be submitted by accident.
188    pub git_ref: String,
189}
190
191/// Placeholder written as `repo.ref` when [`ScaffoldConfig::git_ref`] is left
192/// at its default.
193///
194/// Deliberately not a valid git revision: `ref` must be pinned before the
195/// `description.yml` is submitted, and a scaffold that emitted `main` would
196/// look correct while producing an unreproducible build.
197pub const REF_PLACEHOLDER: &str = "REPLACE_WITH_COMMIT_HASH";
198
199/// The default [`ScaffoldConfig::excluded_platforms`]: the three `DuckDB`-Wasm
200/// targets and `windows_amd64_mingw`.
201///
202/// The community build compiles those with toolchains a Rust extension rarely
203/// needs and often does not build with — emscripten, where the cdylib becomes
204/// a staticlib through `src/wasm_lib.rs`, and the `MinGW` (`windows-gnu`)
205/// target — and most `build: cargo` extensions in `duckdb/community-extensions`
206/// exclude them. Excluding them by default keeps a new extension's first
207/// community build green. (`windows_amd64_mingw` in particular: on
208/// `v2.0-cyanoptera`, extension-ci-tools' `rust.Makefile` passes Cargo no
209/// `--target` for it, so the build would produce the runner's MSVC-ABI DLL and
210/// stamp it `windows_amd64_mingw`.) To opt a platform in, drop it from
211/// `excluded_platforms` (or from both `description.yml` and the workflow's
212/// `exclude_archs` in a generated project) and let the distribution workflow
213/// prove it builds.
214pub const DEFAULT_EXCLUDED_PLATFORMS: &[&str] =
215    &["wasm_mvp", "wasm_eh", "wasm_threads", "windows_amd64_mingw"];
216
217/// The `DuckDB` release a stable-ABI (`C_STRUCT`) scaffold's distribution
218/// workflow builds and tests against: its `duckdb_version`.
219///
220/// This is what `duckdb/community-extensions` builds an extension's `ref`
221/// against (`DUCKDB_LATEST_STABLE` in its `build.yml`).
222///
223/// An unstable-ABI scaffold uses its
224/// [`target_duckdb_version`][ScaffoldConfig::target_duckdb_version] instead,
225/// since that binary loads into no other release.
226pub const DISTRIBUTION_DUCKDB_VERSION: &str = "v2.0.0";
227
228/// The `extension-ci-tools` branch a stable-ABI (`C_STRUCT`) scaffold builds
229/// with, for [`DISTRIBUTION_DUCKDB_VERSION`].
230///
231/// The generated distribution workflow calls `_extension_distribution.yml` at
232/// it and passes it as `ci_tools_version`, `.gitmodules` tracks it, and the
233/// `Makefile`'s setup hint names it. `extension-ci-tools` names its 1.x
234/// branches after `DuckDB` releases (`v1.5.5`, `v1.5.6`, ...) but has no
235/// `v2.0.0` branch: `duckdb/community-extensions` builds `DuckDB` v2.0.0 with
236/// this one.
237pub const DISTRIBUTION_CI_TOOLS_REF: &str = "v2.0-cyanoptera";
238
239/// The `extension-ci-tools` branch the generated project builds with: see
240/// [`DISTRIBUTION_CI_TOOLS_REF`].
241fn extension_ci_tools_ref(config: &ScaffoldConfig) -> &str {
242    if config.use_unstable_c_api {
243        &config.target_duckdb_version
244    } else {
245        DISTRIBUTION_CI_TOOLS_REF
246    }
247}
248
249/// The `DuckDB` release the generated distribution workflow builds against:
250/// see [`DISTRIBUTION_DUCKDB_VERSION`].
251fn distribution_duckdb_version(config: &ScaffoldConfig) -> &str {
252    if config.use_unstable_c_api {
253        &config.target_duckdb_version
254    } else {
255        DISTRIBUTION_DUCKDB_VERSION
256    }
257}
258
259/// Whether the generated project pins `libduckdb-sys` to the bindings of
260/// [`target_duckdb_version`][ScaffoldConfig::target_duckdb_version]: every
261/// build that may use quack-rs's `duckdb-1-5*` features, i.e. one stamped
262/// `C_STRUCT_UNSTABLE`, or `C_STRUCT` with C API v1.5.6.
263fn pins_bindings(config: &ScaffoldConfig) -> bool {
264    config.use_unstable_c_api || config.target_duckdb_version == crate::DUCKDB_API_VERSION_1_5_6
265}
266
267impl Default for ScaffoldConfig {
268    fn default() -> Self {
269        Self {
270            name: String::new(),
271            description: String::new(),
272            version: String::from("0.1.0"),
273            license: String::from("MIT"),
274            maintainer: String::new(),
275            github_repo: String::new(),
276            excluded_platforms: DEFAULT_EXCLUDED_PLATFORMS
277                .iter()
278                .map(|p| (*p).to_string())
279                .collect(),
280            target_duckdb_version: String::from(crate::DUCKDB_API_VERSION),
281            use_unstable_c_api: false,
282            git_ref: String::from(REF_PLACEHOLDER),
283        }
284    }
285}
286
287/// A generated file with its relative path and content.
288#[derive(Debug, Clone)]
289pub struct GeneratedFile {
290    /// Relative path from the project root (e.g., `"src/lib.rs"`).
291    pub path: String,
292    /// File content as a string.
293    pub content: String,
294}
295
296/// What [`generate_scaffold_with_warnings`] produces: the files to write, and
297/// what about the configuration deserves a second look although it was
298/// accepted.
299#[derive(Debug, Clone)]
300#[non_exhaustive]
301pub struct Scaffold {
302    /// The generated files, paths relative to the project root.
303    pub files: Vec<GeneratedFile>,
304    /// One sentence each: a license identifier outside quack-rs's shortlist,
305    /// an exclusion that excludes nothing or everything, an unstable-ABI
306    /// project the community build cannot ship as generated.
307    pub warnings: Vec<String>,
308}
309
310/// Generates the complete set of project files for a new `DuckDB` Rust extension.
311///
312/// Validates the configuration and returns a list of [`GeneratedFile`]s that can be
313/// written to disk. Does NOT write files — callers decide how to persist them.
314/// Warnings about values that were accepted are dropped; use
315/// [`generate_scaffold_with_warnings`] to see them.
316///
317/// # Errors
318///
319/// As [`generate_scaffold_with_warnings`].
320pub fn generate_scaffold(config: &ScaffoldConfig) -> Result<Vec<GeneratedFile>, ExtensionError> {
321    generate_scaffold_with_warnings(config).map(|scaffold| scaffold.files)
322}
323
324/// Generates the project files, and the warnings about the configuration.
325///
326/// # Errors
327///
328/// Returns [`ExtensionError`] if the extension name, license, version (which
329/// must be semver, as it is also the Cargo package version),
330/// description, maintainer, GitHub repository, git ref, excluded platforms or
331/// target `DuckDB` version is invalid — including a hyphenated name, which
332/// `DuckDB` could never load, a name `DuckDB` itself uses (see
333/// [`validate_community_extension_name`]), a license that is not an SPDX
334/// expression (one that is, but names an identifier outside
335/// [`COMMON_SPDX_LICENSES`][crate::validate::spdx::COMMON_SPDX_LICENSES], is a
336/// warning), a version component Cargo cannot read, and an excluded platform
337/// the community build does not build (a group such as `wasm` included).
338///
339/// [`validate_community_extension_name`]: crate::validate::validate_community_extension_name
340pub fn generate_scaffold_with_warnings(
341    config: &ScaffoldConfig,
342) -> Result<Scaffold, ExtensionError> {
343    let mut warnings = Vec::new();
344    checks::check_config(config, &mut warnings)?;
345
346    let mut files = vec![
347        GeneratedFile {
348            path: "Cargo.toml".to_string(),
349            content: templates::generate_cargo_toml(config),
350        },
351        GeneratedFile {
352            path: "Makefile".to_string(),
353            content: templates_make::generate_makefile(config),
354        },
355        GeneratedFile {
356            path: "src/lib.rs".to_string(),
357            content: templates::generate_lib_rs(config),
358        },
359        GeneratedFile {
360            path: "src/wasm_lib.rs".to_string(),
361            content: templates::generate_wasm_lib(),
362        },
363        GeneratedFile {
364            path: "description.yml".to_string(),
365            content: templates::generate_description_yml(config),
366        },
367        GeneratedFile {
368            path: format!("test/sql/{}.test", config.name),
369            content: templates::generate_sqllogictest(config),
370        },
371        GeneratedFile {
372            path: ".github/workflows/extension-ci.yml".to_string(),
373            content: templates_ci::generate_extension_ci(config),
374        },
375        GeneratedFile {
376            path: ".github/workflows/MainDistributionPipeline.yml".to_string(),
377            content: templates_ci::generate_distribution_workflow(config),
378        },
379        GeneratedFile {
380            path: ".gitmodules".to_string(),
381            content: templates::generate_gitmodules(config),
382        },
383        GeneratedFile {
384            path: ".gitignore".to_string(),
385            content: templates::generate_gitignore(),
386        },
387        GeneratedFile {
388            path: ".cargo/config.toml".to_string(),
389            content: templates::generate_cargo_config(),
390        },
391        GeneratedFile {
392            path: "README.md".to_string(),
393            content: templates_docs::generate_readme(config),
394        },
395        GeneratedFile {
396            path: "docs/function_descriptions.csv".to_string(),
397            content: templates_docs::generate_function_descriptions(config),
398        },
399        GeneratedFile {
400            path: "deny.toml".to_string(),
401            content: templates_docs::generate_deny_toml(config),
402        },
403    ];
404    files.extend(licenses::license_files(config));
405
406    Ok(Scaffold { files, warnings })
407}