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}