meson wrap: Subprojects and Dependency Wraps
Meson wraps declare how to fetch and build a dependency as a subproject when it is not found on the system.
When a system dependency is missing, Meson can fall back to building it from source via a .wrap file in subprojects/. In CI you control whether that network fetch is allowed with --wrap-mode.
What it does
A .wrap file under subprojects/ describes a dependency source (a Git repo, a tarball URL, or a WrapDB entry) and patches. meson wrap install fetches a WrapDB wrap; during setup, dependency() falls back to the subproject if the system copy is absent. --wrap-mode controls whether downloading subprojects is permitted.
Common usage
meson wrap install zlib # add a WrapDB wrap
meson wrap list # list available wraps
meson subprojects download # pre-fetch all subprojects
meson setup build --wrap-mode=nodownload # forbid network fetchesOptions
| Command / Flag | What it does |
|---|---|
| meson wrap install <name> | Install a wrap from WrapDB |
| meson subprojects download | Fetch all configured subprojects |
| meson subprojects update | Update subprojects to wrap revisions |
| --wrap-mode=nodownload | Use only already-present subprojects |
| --wrap-mode=forcefallback | Always use the subproject, ignore system libs |
In CI
Pre-fetch subprojects in a cacheable step (meson subprojects download) and cache the subprojects/ directory so the build does not re-download every run. Use --wrap-mode=nodownload in builds that must be hermetic, and --wrap-mode=forcefallback when you want reproducible builds independent of system packages.
Common errors in CI
"Wrap-mode set to nodownload but subproject is not available" means the subproject was not fetched first; download it or relax the wrap mode. "Failed to download" or TLS errors point at network restrictions on the runner; mirror the source or cache subprojects. A hash mismatch means the wrap's source_hash does not match the downloaded tarball.