Managing Packages¶

Adding a Package¶

collider pkg add <name>

Collider resolves the newest version across all configured repositories, installs the wrap file into subprojects/, and populates subprojects/packagecache/ so Meson can build offline.

If the package is already installed (a .wrap file exists in subprojects/), Collider exits with an error rather than redoing work. Pass --force to reinstall:

collider pkg add <name> --force

Collider also resolves transitive dependencies automatically. When the added package depends on other packages (detected via meson introspect --scan-dependencies), Collider installs their wraps too. Only the direct dependency is added to collider.json; transitive deps are recorded in collider.lock when you run collider lock.

Transitive Dependencies¶

Transitive resolution requires at least one configured repository whose index includes dependency_names entries (derived from wrap [provide] sections). When no repository provides this mapping, only the direct package is installed.

By default, Collider applies the following rules to scanned dependencies:

Condition	Behavior
Required dependency	Included automatically.
Optional dependency (`required: false`)	Included with an info message.
Conditional dependency (inside an `if` block)	Excluded. A summary of all skipped conditional deps is shown.
Well-known system dependency (`threads`, `openmp`, etc.)	Silently skipped.
Not found in any configured repository	Skipped (assumed system dependency). Each unknown name is reported once.

If transitive resolution fails after the direct package has been installed, Collider rolls back the direct package (removes its .wrap and cached archives) to avoid a partially installed state.

Including or Excluding Specific Dependencies¶

Fine-grained control over which transitive deps are resolved:

collider pkg add grpc --exclude protobuf
collider pkg add grpc --include libbaz

These overrides are persisted in collider.json and apply only to the dependency they are declared on. When multiple dependencies are resolved together (e.g. during collider lock), each dependency's overrides are scoped to its own dependency scan and do not affect other roots.

Broad Flags¶

collider pkg add grpc --include-conditional    # also resolve conditional deps
collider pkg add grpc --exclude-optional       # skip optional deps

Precedence: --include/--exclude by name > broad flags > defaults.

Version Constraints¶

Pin a version range with --version:

collider pkg add my-lib --version '>=1.2,<2.0'

The constraint is stored in collider.json and enforced on future operations. If collider.json already declares a constraint for the package, it is used automatically.

Offline Mode¶

Add a package using only the local cache:

collider pkg add my-lib --offline

This disables network access and relies on previously cached wraps and archives. See Offline Mode for details.

Note

pkg add does not update collider.lock. Run collider lock explicitly after adding packages to refresh the lockfile.

Removing a Package¶

collider pkg remove <name>

This removes the dependency from collider.json and deletes the installed wrap from subprojects/. The alias pkg rm also works.

When collider.lock exists, Collider also removes orphaned transitive dependencies that are no longer needed by any remaining direct dependency. Only wraps listed in the lockfile are considered for removal; manually added wraps in subprojects/ are never touched. If another direct dependency still requires a shared transitive, it is kept. When no lockfile exists or the resolver cannot determine which wraps are orphaned (e.g. no repository with dependency metadata is configured), a warning is shown and manual cleanup is left to the user.

If the package is still present in collider.lock, Collider warns you to run collider lock to update the lockfile.

Upgrading Packages¶

Upgrade a single package:

collider pkg upgrade my-lib

Upgrade all collider-managed dependencies:

collider pkg upgrade

Collider resolves the newest version allowed by the constraints in collider.json. A package is only reinstalled when the fetched wrap differs from the currently installed one.

To change the version constraint during upgrade:

collider pkg upgrade my-lib --version '>=2.0'

The --offline flag is also supported for upgrades.

Note

pkg upgrade does not update collider.lock. If an upgrade changes the installed version, Collider warns you to run collider lock.

Searching for Packages¶

collider pkg search <pattern>

The pattern is a regular expression matched against package names. Restrict the search to a specific repository:

collider pkg search '^fmt$' --repository wrapdb

Filter by version constraint:

collider pkg search my-lib --version '>=1.0.0'

Search only the local wrap cache:

collider pkg search '.*' --cache

Package Information¶

collider pkg info <name>

Shows available versions across repositories, which versions are cached locally, the currently installed version, and the declared version constraint from collider.json.

Restrict to specific repositories:

collider pkg info my-lib --repository local --repository wrapdb

Dependency Status¶

collider status

Lists tracked Collider dependencies from collider.json and also reports:

Whether the corresponding wrap file exists in subprojects/.
Dependencies declared with "source": "system" in collider.json, shown in a separate system section.
Wraps that are resolved but not declared as direct dependencies, shown as transitive. When collider.lock exists, Collider uses it. Without a lockfile, Collider re-resolves from collider.json when repository metadata is available.
Wraps in subprojects/ that are neither direct nor resolved transitive dependencies, shown as untracked.
When collider.lock exists, lock drift per dependency: ok, modified, or missing.