cargo-depot

1 unstable release

new 0.1.0	Feb 25, 2025

#1079 in Development tools

MIT/Apache

115KB
412 lines

This cargo subcommand allows creating and maintaining a simple cargo alternative registry, which can be served using any webserver (nginx, caddy, miniserve, S3...).

Crates are added to the registry by pointing to their source, as a local folder or remote tarball, via the cargo depot subcommand.

Handling of git and path dependencies

A distinguishing feature compared to other tools (see below) is that git and path dependencies in the added crates will refer to the registry rather than crates.io, with the understanding that these will be pushed to the registry as well. This removes the need for maintaining forks to replace dependencies or complex [patch] or [source] cargo configurations.

For example, a crate with

[dependencies]
git_dep = { version = "0.1.0", git = "https://github.com/cpg314/example.git", tag = "v0.1.0" }
path_dep = { version = "0.1.0", path = "../example" }

will have these dependencies advertised in the index as being in the local registry. With cargo publish, they would refer to the crates.io registry unless a registry property is added.

[!NOTE]
When creating a tarball, cargo package will try to create a lockfile for crates containing binaries or examples. This is problematic, as the registry dependencies will not resolve, unless again a registry property is added and the dependencies are pushed in the right order. To avoid this, cargo-depot will automatically temporarily disable binary targets and examples.

Non-features

On the other hand, this is not a fully-fledged registry; for example, the web API is not implemented.

Usage

Installation

$ cargo install --git https://github.com/cpg314/cargo-local-registry

Initializing and maintaining the registry

Usage: cargo local-registry [OPTIONS] --registry <REGISTRY> [CRATES]...

Arguments:
  [CRATES]...  Paths to crates (local workspaces or HTTP links to tar.gz)

Options:
      --registry <REGISTRY>  Local path to the registry
      --url <URL>            URL of the registry, only needed for initialization
  -h, --help                 Print help
  -V, --version              Print version

Versions that have already been added are skipped.

On Github, tarballs can be downloaded at given commits or tags with the following links:

https://github.com/{owner}/{repo}/archive/{commit}.tar.gz
https://github.com/{owner}/{repo}/archive/refs/tags/{tag}.tar.gz

Serving the files

Use your favourite HTTP server to serve the contents of the registry folder (crates and index folders).

Using the registry

In your .cargo/config.toml:

[registries]
local = { index = "sparse+http://127.0.0.1:3333/index/" }

(replace the URL adequately).

Finally, when declaring your dependencies in Cargo.toml:

crate = {version = "0.1.1", registry = "local" }

Deleting a crate

Delete the line in the index file in the index directory (or the entire file to delete all versions), and the .crate file in the .crate directory. This might break things for users.

Test

The following will create a registry, add crates to it, and finally access them in a crate:

$ cargo make example

See the files in the example directory.

bin+lib cargo-depot