Skip to content

Commit

Permalink
Auto merge of #9249 - ehuss:doc-pkgid-spec, r=alexcrichton
Browse files Browse the repository at this point in the history 
Update pkgid-spec docs.

The old docs for the pkgid spec weren't correct. Specs never supported abbreviated URLs or aliases for the index (like `crates.io`).  This tries to correct that and add a little more detail.

Part of #7725.
  • Loading branch information
@bors
bors committed Mar 10, 2021
2 parents ca476ab + 73dcc8a commit 80c47b7
Showing 1 changed file with 37 additions and 14 deletions.
51 changes: 37 additions & 14 deletions src/doc/src/reference/pkgid-spec.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,37 +4,60 @@

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
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.

The specification may be fully qualified, such as
`https://github.com/rust-lang/crates.io-index#regex:1.4.3` or it may be
abbreviated, such as `regex`. The abbreviated form may be used as long as it
uniquely identifies a single package in the dependency graph. If there is
ambiguity, additional qualifiers can be added to make it unique. For example,
if there are two versions of the `regex` package in the graph, then it can be
qualified with a version to make it unique, such as `regex:1.4.3`.

#### Specification grammar

The formal grammar for a Package Id Specification is:

```notrust
pkgid := pkgname
| [ proto "://" ] hostname-and-path [ "#" ( pkgname | semver ) ]
spec := pkgname
| proto "://" hostname-and-path [ "#" ( pkgname | semver ) ]
pkgname := name [ ":" semver ]
proto := "http" | "git" | ...
```

Here, brackets indicate that the contents are optional.

The URL form can be used for git dependencies, or to differentiate packages
that come from different sources such as different registries.

#### 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` |
The following are references to the `regex` package on `crates.io`:

| Spec | Name | Version |
|:------------------------------------------------------------|:-------:|:-------:|
| `regex` | `regex` | `*` |
| `regex:1.4.3` | `regex` | `1.4.3` |
| `https://github.com/rust-lang/crates.io-index#regex` | `regex` | `*` |
| `https://github.com/rust-lang/crates.io-index#regex:1.4.3` | `regex` | `1.4.3` |

The following are some examples of specs for several different git dependencies:

| Spec | Name | Version |
|:----------------------------------------------------------|:----------------:|:--------:|
| `https://github.com/rust-lang/cargo#0.52.0` | `cargo` | `0.52.0` |
| `https://github.com/rust-lang/cargo#cargo-platform:0.1.1` | <nobr>`cargo-platform`</nobr> | `0.1.1` |
| `ssh://git@github.com/rust-lang/regex.git#regex:1.4.3` | `regex` | `1.4.3` |

Local packages on the filesystem can use `file://` URLs to reference them:

| Spec | Name | Version |
|:---------------------------------------|:-----:|:-------:|
| `file:///path/to/my/project/foo` | `foo` | `*` |
| `file:///path/to/my/project/foo#1.1.8` | `foo` | `1.1.8` |

#### Brevity of specifications

Expand Down

0 comments on commit 80c47b7

Please sign in to comment.