Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update pkgid-spec docs. #9249

Merged
merged 1 commit into from
Mar 10, 2021
Merged

Update pkgid-spec docs. #9249

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 37 additions & 14 deletions src/doc/src/reference/pkgid-spec.md
View file
Open in desktop
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://[email protected]/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