Search and add packages

Overview

A package is a reusable C3 library in a .c3l directory. Its manifest declares the library’s name and any C3 or native dependencies it needs.

A registry is a catalog of packages, their versions, and where to fetch their source code. Packages are identified by namespace/name, such as vendor/raylib.

Search finds packages in your configured registries; show lists their versions. Adding a registry package selects its latest version unless you request an exact published version with @VERSION. c3pm uses Nix to fetch its source and resolve dependencies for your project. You can also add a repository, archive, or local directory directly, without a registry.

Command aliases

Each pair accepts the same arguments and options.

The examples below use the short commands.

Searching for a package

Search by package name, description, or tag:

c3pm search raylib
c3pm search                         # List all packages
c3pm search image --tag graphics
c3pm search raylib --registry default

If no registries are configured, the first search adds the default. Later searches work offline; run c3pm registry update to refresh results.

Add a dependency

c3pm uses the library manifest’s provides value as the dependency name. Pass --name NAME to assert an expected name.

Adding from registry

Install the package’s latest registered version:

c3pm add vendor/raylib
c3pm add raylib

Choose a published version instead of latest:

c3pm dep add raylib@5.5
c3pm add vendor/raylib@5.5

The version must match an entry in the package’s versions list exactly. For example, 5.5 and 5.5.0 are different version labels. The name alone works only when it is unique across all configured registries and namespaces. Run c3pm registry update to refresh available versions.

Adding directly

Specify a repository, archive, or local directory:

c3pm add github:SMFloris/c3c-vendor \
  --rev c3pm \
  --subdir libraries/sqlite3.c3l

Supported source forms:

Pass --subdir PATH when the .c3l directory is below the source root.

Remote sources are fetched through Nix and recorded in .c3pm/nix/flake.lock.

Show package versions

Inspect a registry package and all its available versions:

c3pm show vendor/raylib
c3pm show raylib

The unqualified name works when the package name is unique across configured registries. Use show to find exact version labels before adding a specific version.

Update a dependency

Update an installed registry package to a specific published version, or omit @VERSION to use the registry’s latest:

c3pm dep update raylib@6
c3pm dep update raylib

The update replaces the dependency’s pinned source in project.json and synchronizes the project. It also updates the release recorded under vendor.c3pm.registry. If the new release has a different C3 provides name, such as raylib55 becoming raylib6, c3pm changes the dependency name in project targets too. Update your source imports to the new module name when needed.

Registry updates require a recorded vendor.c3pm.registry reference. c3pm does not infer one by matching a directly added source against a registry package.

For a dependency added directly from GitHub or Git, specify its C3 dependency name and the new revision explicitly. For an HTTPS archive, specify its new SHA-256 hash:

c3pm dep update sqlite3 --rev v3.50.0
c3pm dep update mybinding --sha256 sha256-NEW_HASH

Direct updates retain the original source location and subdir. The new source must still provide the same C3 dependency name. A path: dependency has no revision or archive hash to update; change the files at that path and run c3pm install.

List dependencies and links

For example, from a C3 project:

c3pm list
c3pm list --for-target server
c3pm dep list
c3pm link list

All three accept --for-target TARGET. For c3pm list, the filter applies to both dependencies and links.

Target-specific dependencies

Add or remove a dependency for one target with:

--for-target TARGET

Inspect dependencies with:

c3pm dep list
c3pm dep list --for-target server

Remove a dependency

c3pm remove NAME

Example:

c3pm remove sqlite3

Removing a direct dependency recalculates the graph and prunes generated C3 nodes and source inputs that are no longer reachable. A shared transitive dependency remains when another dependency still uses it.