Depot

Note: This page is focused on two tasks: using Depot, and creating Depot specs. The commands and fields below are taken from the current Depot CLI and spec parser in depot's source code.

Using Depot

Depot’s day-to-day workflow is split between installing, building, updating, and querying. The main commands share common execution flags such as --dry-run, --test-deps, --clean, and -r or --rootfs for operating on another root filesystem.

Task	Command	Notes
Install from spec	depot install packages/zlib.toml	Builds and installs from a TOML spec.
Install from archive	depot install zlib-1.2.11-1-x86_64.depot.pkg.tar.zst	Archive installs verify checksums and detached minisign signatures.
Build only	depot build packages/zlib.toml	Produces a package archive without installing it.
Update packages	depot update	Updates all installed packages with available upgrades.
Inspect package info	depot info zlib	Works with an installed package name or a spec path.
Search repos	depot search zlib	Searches configured source and binary repos by name or provided features.

Installing packages

The install command accepts one or more package names, spec paths, or package archives. Before acting, Depot resolves a dependency plan and then executes it in dependency order.

depot install packages/zlib.toml
depot install --yes --dry-run packages/zlib.toml
depot install zlib-1.2.11-1-x86_64.depot.pkg.tar.zst

Common flags:

• --yes answers prompts automatically and chooses the default provider.
• --dry-run prints the plan without building or installing.
• --test-deps includes declared test dependencies in dependency installation.
• -r /mnt installs into an alternate root filesystem instead of /.

Tip: Use depot install --dry-run first when you are not sure which provider or dependency chain Depot will choose.

Building packages

The build command is the safest way to validate a new spec without immediately changing the system. It creates a package archive and can optionally install dependencies or install the finished archive afterward.

depot build packages/zlib.toml
depot build --install-deps packages/zlib.toml
depot build --install --cleanup-deps packages/zlib.toml

• --install-deps installs missing build, runtime, and optionally test dependencies before the build.
• --cleanup-deps removes dependencies that were auto-installed just for this build after the command finishes.
• --install installs the built package after the archive is created.

Note: Missing test dependencies automatically disable test execution unless --test-deps is used or Depot is configured to install test dependencies by default.

Updating and querying

Depot can update installed packages, inspect local ownership, search configured repos, and scan a directory tree of specs for newer upstream versions.

depot update
depot update depot
depot search zlib
depot search --files libz.so
depot owns /usr/bin/zsh
depot list
depot check packages/

Working on another root filesystem

Commands such as install, build, update, info, search, owns, list, and config accept -r to target another root.

depot install -r /mnt packages/zlib.toml
depot update -r /mnt
depot owns -r /mnt /usr/bin/clang

Creating specs

Depot specs are TOML files parsed into a PackageSpec. The core pieces are package metadata, sources, build configuration, and dependency lists. Advanced specs can also define extra outputs, alternatives, package-specific dependency overrides, manual sources, and lib32 variants.

Warning

A non-meta package must define at least one source entry or one manual_sources entry. Only build.type = "meta" may omit both.

Section	Purpose
[package]	Name, version, revision, description, homepage, license, and optional stream metadata such as real_name.
[[source]]	Source URL, checksum, extract directory, patches, post-extract hooks, and optional git cherry-picks.
[[manual_sources]]	Files or URLs copied into the build work directory before normal source fetching.
[build] and [build.flags]	Build system selection plus configure args, toolchain flags, hooks, install prefixes, and staging behavior.
[dependencies]	Separated build, runtime, test, and optional dependencies.
[alternatives]	Virtual provides, conflicts, and replacements.

Manual spec creation

Writing the spec yourself gives full control and is the best fit for packages that need patches, custom hooks, multiple outputs, alternative providers, or unusual build flags.

Minimal example

[package]
name = "example"
version = "1.0.0"
description = "An example package"
homepage = "https://example.com"
license = "MIT"

[[source]]
url = "https://example.com/example-$version.tar.gz"
sha256 = "..."
extract_dir = "example-$version"

[build]
type = "autotools"

[build.flags]
configure = ["--enable-feature"]

[dependencies]
build = ["gcc", "make"]
runtime = ["libc"]
optional = ["bash-completion"]

Sources and manual sources

Standard sources are declared with [[source]]. Each source entry can define url, sha256, extract_dir, patches, post_extract, and cherry_pick for git-based sources.

Manual sources are separate. They are copied in before fetching and can use either local paths or remote URLs per block, but not both at the same time.

[[manual_sources]]
file = "depot.pub"
dest = "keys/depot.pub"

[[manual_sources]]
url = "https://example.com/extra.patch"
sha256 = "skip"
dest = "patches/extra.patch"

Note: When a single manual_sources block contains multiple files or URLs, Depot does not allow a shared dest or a single shared checksum for that block.

Build types

Depot currently supports the following build types:

autotools cmake meson perl custom python rust makefile bin meta

Common flags live under [build.flags]. Useful fields include configure, build_dir, source_subdir, cflags, cxxflags, ldflags, ltoflags, post_configure, post_compile, post_install, split_docs, and builder-specific options such as config_settings for Python or makefile_commandsfor Makefile packages.

Dependencies and alternatives

Dependencies are grouped into build, runtime, test, and optional. Alternatives can define provides, conflicts, and replaces.

[dependencies]
build = ["meson", "ninja"]
runtime = ["zlib"]
test = ["pytest"]
optional = ["bash-completion"]

[alternatives]
provides = ["sh"]
conflicts = ["busybox-sh"]

Build flags reference

Most spec tuning happens under [build.flags]. The parser accepts a large set of fields, including several alias spellings for dashed and underscored names. The tables below focus on the primary field names.

Toolchain and compiler flags

Field	Purpose
cflags, cxxflags, ldflags	Extra compiler and linker flags exported to the build environment.
replace_cflags, replace_cxxflags, replace_ldflags	Ordered replacement rules applied before export. Entries can use old=>new.
ltoflags, rustltoflags, replace_ltoflags	LTO-specific flags and replacement rules. When use_lto is true, these are injected into normal flags.
rustflags, replace_rustflags	Rust-specific flag export and replacement rules.
cc, cxx, ar, ld, cpp	Overrides for the toolchain executables exported to supported builders.
libc	Dynamic loader path override for packages that need an explicit runtime loader setting.
no_flags	Disables exporting CFLAGS, CXXFLAGS, and LDFLAGS for this build.
use_lto	Controls whether ltoflags are automatically appended to the regular compiler and linker flags.

Build layout and install directories

Field	Purpose
prefix	Top-level install prefix, defaulting to /usr.
bindir, sbindir, libdir, libexecdir	Overrides for executable and library install destinations.
sysconfdir, localstatedir, sharedstatedir	Overrides for configuration and state directory installation paths.
includedir, datarootdir, datadir, mandir, infodir	Header, data, man page, and info page directory overrides.
source_subdir	Uses a subdirectory inside the extracted source as the real build root.
build_dir	Uses a separate build directory relative to the source root.

Build system flow and hooks

Field	Purpose
configure	Generic configure or setup arguments for supported builders.
configure_lib32	lib32-specific configure arguments that replace the normal configure set when present.
configure_file	Autotools configure script path when the script is not at the source root.
post_configure, post_compile, post_install	Commands run after the configure, compile, and install stages.
post_configure_lib32, post_compile_lib32, post_install_lib32	lib32-specific hook commands.
skip_tests	Skips automatic build-system test execution such as make check or make test.
config_settings	PEP 517 config settings for Python builds, typically written as KEY=VALUE.

Make and make-like execution

Field	Purpose
make_exec, makeflags	Choose the make-like executable and the MAKEFLAGS string passed to it.
make_vars, make_test_vars, make_install_vars	Variable overrides for build, test, and install phases.
make_target, make_targets	Target or targets for the compile phase.
make_test_target, make_test_targets	Target or targets for the test phase.
make_install_target, make_install_targets	Target or targets for the install phase.
make_dirs, make_test_dirs, make_install_dirs	Subdirectories where build, test, and install phases should run.
makefile_commands, makefile_install_commands	Explicit command lists used by build.type = “makefile”.

Multilib, docs, and staging behavior

Field	Purpose
build_32, lib32_only	Enable a lib32 companion build or build only the generated lib32-* output.
cflags_lib32, cxxflags_lib32	lib32-only compiler flags.
replace_cflags_lib32, replace_cxxflags_lib32	Replacement rules for the lib32 compiler flags.
split_docs, doc_dirs	Split documentation into a generated -docs output and extend which doc directories are moved.
keep	Preserve existing files on install and place package replacements next to them as .depotnew files.
no_strip	Disables automatic ELF stripping during staging.
no_delete_static	Keeps static libraries instead of removing *.a files during staging.
no_compress_man	Disables automatic zstd compression of man pages.

Cross and builder-specific fields

Field	Purpose
host_build	Runs an additional native host-side helper build when the target architecture differs.
chost, cbuild, carch	Target triple, build triple, and architecture metadata exported for builds that need them.
profile, target, cargs	Rust-specific build profile, target triple, and extra Cargo arguments.
passthrough_env	Extra host environment variable names to export unchanged into build commands.
binary_type	Package type metadata for build.type = “bin”.

Example

[build.flags]
build_dir = "build"
source_subdir = "src"
configure = ["--disable-static", "--enable-shared"]
cflags = ["-O2", "-pipe"]
replace_cflags = ["-O2=>-O3"]
ltoflags = ["-flto=thin"]
post_install = ["rm -f $DESTDIR/usr/share/info/dir"]
split_docs = true
doc_dirs = ["/usr/share/gtk-doc", "/usr/share/devhelp"]
make_exec = "ninja"
make_install_target = "install"
passthrough_env = ["CCACHE_DIR", "CARGO_HOME"]

Tip: Depot accepts several dashed and underscored aliases for many flags, including forms like split-docs, configure-lib32, and make-install-target. The examples on this page use the canonical field names for consistency.

Interactive creator

Depot includes an interactive spec generator. It asks a series of questions and writes a minimal TOML file, defaulting to <package>.toml unless an explicit output path is supplied.

depot make-spec
depot make-spec -o packages/zlib.toml

The interactive flow covers:

• package name, version, description, homepage, and one or more licenses
• build system selection, including meta packages
• source URL, checksum, and extract directory
• optional advanced prompts for patches, manual sources, toolchain overrides, configure options, and post-build hooks
• separate runtime, build, test, and optional dependency lists

A few details from the current implementation are useful to know:

• it asks early whether the package is a GNU project and can pre-fill GNU-style defaults
• for reachable URLs, it tries to compute a default SHA256 automatically
• if the output file already exists, it asks before overwriting it
• the generated file is intentionally compact and omits default or empty fields

Tip: depot make-spec is a good starting point, not the end of the job. After generation, it is normal to edit the TOML manually to add extra outputs, alternatives, package-specific overrides, or lib32-specific behavior.

See also

• Docs index
• Depot in Features
• Package browser
• Download Vertex Linux