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 and already declared directly, Collider exits with an error rather than redoing work. Pass --force to reinstall:

collider pkg add <name> --force

If the wrap is already present only because it was installed transitively for another dependency, pkg add promotes it into collider.json as a direct dependency without reinstalling it.

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:

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.

Removing a Package¶

collider pkg remove <name>

This removes the dependency from collider.json. The alias pkg rm also works.

pkg remove is conservative about installed artifacts. If another dependency still requires the package transitively, Collider keeps the wrap in place. If Collider cannot determine safely whether the package is still needed, it also leaves the wrap in place and warns instead of deleting it.

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

To also clean up orphaned transitive dependencies in one step, use:

collider pkg remove --prune <name>

Pruning Orphaned Dependencies¶

collider pkg prune

pkg prune scans subprojects/ for transitive wraps that are no longer needed by any declared Collider dependency and removes them. Only wraps proven to be Collider-managed (listed in collider.lock) are eligible; manually placed wraps are never touched.

If no lockfile exists, prune warns and does nothing. Running collider lock creates ownership metadata for future operations, but existing leftover wraps may still need to be removed manually.

Pruning does not update collider.lock; after wraps are removed, Collider warns you to run collider lock to refresh the lockfile.

Use --dry-run to preview what would be removed without actually deleting anything:

collider pkg prune --dry-run

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.

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.