From 6b658b63410c77cf76cc43e11dc98153acb8fbf8 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 27 Aug 2021 08:28:42 -0700 Subject: [PATCH] Add docs on new index fields. --- src/git.rs | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/src/git.rs b/src/git.rs index 5b140e7725..468d25d60e 100644 --- a/src/git.rs +++ b/src/git.rs @@ -62,11 +62,39 @@ pub struct Crate { pub deps: Vec, pub cksum: String, pub features: HashMap>, + /// This field contains features with new, extended syntax. Specifically, + /// namespaced features (`dep:`) and weak dependencies (`pkg?/feat`). + /// + /// It is only populated if a feature uses the new syntax. Cargo merges it + /// on top of the `features` field when reading the entries. + /// + /// This is separated from `features` because versions older than 1.19 + /// will fail to load due to not being able to parse the new syntax, even + /// with a `Cargo.lock` file. #[serde(skip_serializing_if = "Option::is_none")] pub features2: Option>>, pub yanked: Option, #[serde(default)] pub links: Option, + /// The schema version for this entry. + /// + /// If this is None, it defaults to version 1. Entries with unknown + /// versions are ignored by cargo starting with 1.51. + /// + /// Version `2` format adds the `features2` field. + /// + /// This provides a method to safely introduce changes to index entries + /// and allow older versions of cargo to ignore newer entries it doesn't + /// understand. This is honored as of 1.51, so unfortunately older + /// versions will ignore it, and potentially misinterpret version 2 and + /// newer entries. + /// + /// The intent is that versions older than 1.51 will work with a + /// pre-existing `Cargo.lock`, but they may not correctly process `cargo + /// update` or build a lock from scratch. In that case, cargo may + /// incorrectly select a new package that uses a new index format. A + /// workaround is to downgrade any packages that are incompatible with the + /// `--precise` flag of `cargo update`. #[serde(skip_serializing_if = "Option::is_none")] pub v: Option, }