Package ID Specifications
Package ID specifications
Subcommands of Cargo frequently need to refer to a particular package within a dependency graph for various operations like updating, cleaning, building, etc. To solve this problem, Cargo supports Package ID Specifications. A specification is a string which is used to uniquely refer to one package within a graph of packages.
Specification grammar
The formal grammar for a Package Id Specification is:
pkgid := pkgname
| [ proto "://" ] hostname-and-path [ "#" ( pkgname | semver ) ]
pkgname := name [ ":" semver ]
proto := "http" | "git" | ...
Here, brackets indicate that the contents are optional.
Example specifications
These could all be references to a package foo version 1.2.3 from the
registry at crates.io
| pkgid | name | version | url |
|---|---|---|---|
foo | foo | * | * |
foo:1.2.3 | foo | 1.2.3 | * |
crates.io/foo | foo | * | *://crates.io/foo |
crates.io/foo#1.2.3 | foo | 1.2.3 | *://crates.io/foo |
crates.io/bar#foo:1.2.3 | foo | 1.2.3 | *://crates.io/bar |
https://crates.io/foo#1.2.3 | foo | 1.2.3 | https://crates.io/foo |
Brevity of specifications
The goal of this is to enable both succinct and exhaustive syntaxes for referring to packages in a dependency graph. Ambiguous references may refer to one or more packages. Most commands generate an error if more than one package could be referred to with the same specification.